2.3.3.3.1. Directories

From the seven main directories in your repository that PyPackIT manages and works with, the GitHub directory and the Docs directory have fixed paths according to GitHub requirements, while the path to the other five directories can be customized. As discussed before, Customizing the path to the control center directory requires a configuration file outside the control center directory. The path to the remaining four directories, i.e., the source, tests, website, and local directories, along with the paths to subdirectories of the local directory, can be customized using the path.yaml file in your repository’s control center, as described in this section.

2.3.3.3.1.1. Setting

The path.yaml file accepts a key dir, where the value is an object with keys source, tests, website, and local, corresponding to the four main directories mentioned above. The value of the source, tests, and website keys must be a string representing the custom path to the corresponding directory, relative to the root of the repository. The local key accepts an object with keys root, cache, and report. The root key must be set to a string defining the path to the local directory itself. The cache and report keys correspond to the cache and report subdirectories of the local directory; they accept an object with a key root that must be set to a string defining the path to the corresponding subdirectory, relative to the root of the local directory. In addition, they each define paths to other subdirectories of the corresponding cache/report subdirectory, each used for a specific tool. By default, the following keys are defined for both the cache and report subdirectories: repodynamics, coverage, mypy, pylint, pytest, and ruff. Each of these keys must be set to a string defining the path to the cache/report subdirectory for that tool, relative to the root of the corresponding cache/report subdirectory.

Example

The default settings for the local key are as follows:

Snippet 2.3.2 🗂 path.yaml

dir:
  local:
    root: .local
    cache:
      root: cache
      repodynamics: repodynamics
      coverage: coverage
      mypy: mypy
      pylint: pylint
      pytest: pytest
      ruff: ruff
    report:
      root: report
      repodynamics: repodynamics
      coverage: coverage
      mypy: mypy
      pylint: pylint
      pytest: pytest
      ruff: ruff

This corresponds to the following directory structure for the local directory:

📦 <REPOSITORY-ROOT>
 ┃
 ┗ 🗂 .local
   ┃
   ┣ 🗂 cache
   ┃ ┃
   ┃ ┣ 🗂 coverage
   ┃ ┃
   ┃ ┣ 🗂 mypy
   ┃ ┃
   ┃ ┣ 🗂 pylint
   ┃ ┃
   ┃ ┣ 🗂 pytest
   ┃ ┃
   ┃ ┣ 🗂 repodynamics
   ┃ ┃
   ┃ ┗ 🗂 ruff
   ┃
   ┗ 🗂 report
     ┃
     ┣ 🗂 coverage
     ┃
     ┣ 🗂 mypy
     ┃
     ┣ 🗂 pylint
     ┃
     ┣ 🗂 pytest
     ┃
     ┣ 🗂 repodynamics
     ┃
     ┗ 🗂 ruff

You can also add other custom keys under dir.local.cache and dir.local.report for other tools that you use, and reference them in the corresponding configuration files. Note that you do not have to specify all keys in the path.yaml file; for all keys that are not specified, PyPackIT will use the default values. Also, you can entirely omit the path.yaml file if you do not want to customize any paths.

Example

For example, if you only want to

• change the path of the source directory to my_source_directory,

• change the path of the cache subdirectory to my_cache_directory, and

• add a new subdirectory my_tool_subdirectory under the report subdirectory for the tool my_tool,

then your path.yaml file should look like this:

Snippet 2.3.3 🗂 path.yaml

dir:
  source: my_source_directory
  local:
    cache:
      root: my_cache_directory
    report:
      my_tool: my_tool

Important Considerations

• You must also manually create/rename/move the corresponding directories to match the set path, in the same commit where you create/modify/delete the path.yaml file.

• All four main directories must be orthogonal to all other main directories in your repository, meaning that they cannot be a subdirectory of any other main directory.

2.3.3.3.1.2. Usage

PyPackIT automatically manages a variety of files in your repository’s main directories, and performs a number of tasks that require access to these files. For example, to run your tests and build your website, PyPackIT needs to know the path to tests and website directories. In addition, these paths are used as substitutions in a number of other configuration files for your project, so that you do not have to manually update these files when you change a path. The following are just a few examples of configuration files where these paths are used:

Snippet 2.3.4 🗂 package_python/build.toml

[tool.setuptools.packages.find]
where = [ "${‎{ path.dir.source }}" ]

[tool.versioningit.onbuild]
source-file = "${‎{ path.dir.source }}/${‎{ package.name }}/__init__.py"

Snippet 2.3.5 🗂 package_python/tools/mypy.toml

[tool.mypy]
cache_dir = "${‎{ path.dir.local.cache.mypy }}"
any_exprs_report = "${‎{ path.dir.local.report.mypy }}"
html_report = "${‎{ path.dir.local.report.mypy }}"
linecount_report = "${‎{ path.dir.local.report.mypy }}"
linecoverage_report = "${‎{ path.dir.local.report.mypy }}"
lineprecision_report = "${‎{ path.dir.local.report.mypy }}"
txt_report = "${‎{ path.dir.local.report.mypy }}"

Snippet 2.3.6 🗂 package_python/tools/ruff.toml

[tool.ruff]
cache-dir = "${‎{ path.dir.local.cache.ruff }}"

Snippet 2.3.7 🗂 ui/web.yaml

readthedocs:
  conda:
    environment: ${‎{ path.dir.website }}/requirements.yaml
  sphinx:
    configuration: ${‎{ path.dir.website }}/source/conf.py