Structure#
In addition to several files in the root directory, PyPackIT recognizes and works with seven main directories and their contents in your repository:
The main control center of the repository, containing all information, configurations and metadata for the entire project.
The directory where GitHub looks for GitHub Actions workflow files and other configuration files. PyPackIT also uses this directory to store some of its own data and settings, as well as configuration files for other external tools.
Contains the top-level package directory and thus all source code of your package.
Contains your package’s entire test suite as a standalone Python package.
All contents and configuration files required to build your website are stored in this directory.
One of the directories where GitHub looks for the community health files of your repository, along with some other configuration files. By default, PyPackIT also places the website directory inside this directory.
When working on a local clone of the repository, this directory is used to store cached data, reports, and logs.
PyPackIT also recognizes and works with several files in the root directory of your repository.
These directories all have their default names and locations, and are created automatically when you initialize a new repository from the PyPackIT repository template. Therefore, your repository will have the following main directory structure (files and subdirectories omitted) by default:
📦 <root> ┃ ┣ 🗂 .github ┃ ┣ 🗂 .local ┃ ┣ 🗂 .meta ┃ ┣ 🗂 docs ┃ ┃ ┃ ┗ 🗂 website ┃ ┣ 🗂 src ┃ ┗ 🗂 tests
Apart from the GitHub and Docs directories, whose names and locations are fixed due to GitHub’s requirements, you can customize the paths to all other directories, including the control center directory. However, each directory must conform to a specific substructure, meaning that PyPackIT will look for specific files and subdirectories in specific locations inside each directory, as described in the corresponding sections. Also, all directories must be orthogonal to each other, meaning that none of them can be a subdirectory of another.
GitHub Directory#
Every repository must contain a ./.github directory,
i.e., a directory named .github located at the root (./) of the repository.
This is where GitHub looks for GitHub Actions workflow files
(.yaml files in the ./.github/workflows directory) and other configuration files,
such as issue-, discussion-, and pull request templates.
When a repository is first initialized from the PyPackIT template,
the ./.github directory will only contain workflow files.
These are configurations that define the continuous integration and delivery (CI/CD)
pipelines of the repository, allowing the whole development and maintenance process of your project
to be automatically managed by PyPackIT.
In general, you should never modify these files directly, since all configurations and data that
are specific to each project are read automatically from the repository’s meta content (discussed below).
The only exception is when you want to add a new feature/functionality to your pipelines,
which is not covered by PyPackIT and is completely orthogonal to its functionalities.
After the repository is configured, a number of other files and directories
will also be automatically added to the ./.github directory,
including issue-, discussion-, and pull request templates, and other GitHub configuration files.
PyPackIT also uses the ./.github directory to store some of its own data and settings,
as well as configuration files for other external tools that are used by PyPackIT.
You must never modify these files directly, as they are dynamic files that are automatically
generated and updated by PyPackIT according to the repository’s meta content.
Control Center Directory#
The meta directory is the main control center of your repository,
where all configurations, metadata, and settings
for your GitHub repository (and its corresponding git repository),
package, website, development pipeline, and other tools are stored in one place.
When you apply a change to the repository’s meta content and push it to the remote repository,
PyPackIT will automatically apply the corresponding changes to entire repository and its content,
so that the repository is always in a consistent state with its meta content.
This is the main mechanism that PyPackIT uses to manage your repository and project,
so you must never modify any configuration directly, but always through the meta content.
This directory is named .meta by default, and is located at the root of the repository.
You can change the name and location of your repository’s meta directory,
but it must have a specific substructure, meaning that PyPackIT will look for
specific files and directories in specific locations inside the meta directory
to read the corresponding configurations and data from.
Local Directory#
This directory is used to store local files,
such as cache files, logs and reports from various tools.
It will be automatically added to the .gitignore file.
Source Directory#
The source directory is where all source code of your package is stored.
This directory is named src by default, and is located at the root of the repository.
However, you can change its name and location via the meta content.
PyPackIT follows the
Setuptools’s src-layout
for package discovery.
This means that your source directory must contain a single top-level package directory,
which must at least contain a __init__.py file. The name of this top-level package directory
defines the import name of your package. You must never rename the top-level package directory directly;
instead, PyPackIT will automatically rename it for you
when you change the package name in the meta content. PyPackIT will also automatically
update all import statements in your source code to reflect the new package name.
When the repository is first initialized, PyPackIT will automatically create the source directory
and the top-level package directory, along with the top-level __init__.py file.
Note that the docstring of the top-level __init__.py file is also dynamic. Therefore, while you can
change the content of the __init__.py file, you must never change the docstring directly, but always
through the meta content.
Cache Directory#
Important Considerations
You must also manually rename/move the control center directory to match the new path in the same commit where you create/modify/delete the path declaration file.
The control center directory must be orthogonal to all other main directories in your repository, meaning that it cannot be a subdirectory of any other main directory.