repo structure¶
Main structure¶
Your new repo will have the following structure:
/docs # only if you enabled documentation builds
├── index.md
└── .pages
/src/{{project_name}}
├── __init__.py
└── example.py
/test/test_{{project_name}}
├── __init__.py
└── test_example.py
pyproject.toml
README.md
- If you use VSCode, load your project as a workspace by opening your project's folder. This will set up VSCode with convenient settings and recommended extensions.
- Put your python code in
src/{{project_name}}
, tests intest/test_{{project_name}}
, and markdown documentation indocs
. - When you run
poetry install
it will install thesrc
package in editable mode, so every package and module you add will be available to import locally in your project. - Add new dependencies to
pyproject.toml
and runpoetry install
to install them or runpoetry add <package>
to add a new dependency. Runpoetry update
to update all dependencies. Poetry will create a.venv
folder with a virtual environment inside your project (configurable withpoetry.toml
). - To run tests, use
poetry run pytest
, or if you use direnv and have enabled it, simply runpytest
. - You will only get the
docs
folder if you enabled documentation builds in the copier prompts. Add your markdown documentation to thedocs
folder and runbin/serve-docs
to see a live preview (orserve-docs
if you use direnv). Make changes to.pages
to edit your navigation pane. - Edit your
README.md
file to include information about your project, how to install it, how to use it, and any other relevant information you may want to share.
Configuration, commands and workflows¶
Further relevant configuration files, binaries and workflows are shown in the following tree:
ruff.toml
pyrightconfig.json
.codespellrc
/bin
/.github
├── dependabot.yml
└── workflows
├── main.yml
├── pr.yml
└── weekly.yml
.envrc
- The
ruff.toml
file is used by ruff to configure code formatting and linting rules, including black, isort, flake8, and others. Use this file to configure your code style and linting rules and exceptions. It runs fast and it is integrated in VSCode with the ruff extension. - The
pyrightconfig.json
file is used by pyright to configure type checking rules and exceptions. You can add exceptions to thepyrightconfig.json
file to suppress warnings or errors. We encourage you to use type annotations in your code to help detect errors early, but most importantly, to improve readability of your code (to your future self and others). - The
.codespellrc
file is used by codespell to check spelling in your files and code. If codespell detects spelling errors, it will suggest corrections. You can add exceptions to the.codespellrc
file. - The
bin
folder includes scripts to help you with common tasks. For examplebin/check-all
will run all checks includingpre-commit
,ruff
,pytest
,pyright
andmkdocs
(if enabled). You should run this check prior to committing changes to your repository or pushing to your remote. - The
.github
folder includes.dependabot.yml
for automated dependency updates in GitHub, and workflows folder for automatic CI checks on pull requests, pushes, and weekly scheduled tasks. - The
.envrc
file is used by direnv to manage environment variables and load python virtual environments automatically. We strongly encourage you to use direnv to manage your development environment for its convenience.
Pre-commit, commitizen and documentation (optional)¶
Other configuration files may include (depending on your choices during the copier process):
- Pre-commit is a tool to run code formatting and linting before committing changes.
You can run
pre-commit run --all-files
to run a bunch of checks manually. Add new hooks or remove existing ones in the.pre-commit-config.yaml
file. - The
.cz.toml
file is used by commitizen to write commit message. It relies on thecz-conventional-gitmoji
plugin to combine gitmoji and conventional commits. Write a commit asfix: correct typo in README
orfeat: add new feature
andpre-commit
will prepend a corresponding gitmoji to your commit message. Runcz commit
to write a commit message interactively listing all possible types and options. - Finally, the
mkdocs.yml
and.apidoc_conf.py
file are used by mkdocs and sphinx to configure your documentation build and API reference docstrings.