Development

Getting the source

git clone https://github.com/Pinto-Katende-Jonathan/pyfilechoose.git
cd pyfilechoose

Setting up an environment

With uv, which creates and manages the virtualenv for you:

uv sync --extra dev
uv run pytest

With pip:

python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest

Project layout

pyfilechoose/
├── src/pyfilechoose/
│   ├── __init__.py     # exports + __version__
│   ├── core.py         # implementation
│   └── py.typed        # PEP 561 marker
├── tests/
│   └── test_core.py
├── docs/               # this documentation
├── pyproject.toml
├── mkdocs.yml
├── CHANGELOG.md
└── README.md

The package uses the src/ layout, which keeps the import path the same in development and after install and prevents accidentally importing the source tree instead of the installed package.

Running the tests

pytest

The tests replace the Tk dialog with a fake so they run headless, with no display and no real window. They cover the logic around the dialog: path normalization, the FileNotFoundError on cancel, and argument forwarding. The _open_dialog helper is monkeypatched, so the suite never opens a real dialog.

Common commands

The repository ships task shortcuts so you do not have to remember the full commands. On Windows use tasks.ps1; on Linux/macOS use make.

Action	Windows	Linux / macOS
Install with dev + docs extras	.\tasks.ps1 install	make install
Preview the docs	.\tasks.ps1 docs-serve	make docs-serve
Build the docs	.\tasks.ps1 docs-build	make docs-build
Deploy the docs	.\tasks.ps1 docs-deploy	make docs-deploy
Run the tests	.\tasks.ps1 test	make test
Build the package	.\tasks.ps1 build	make build

Building the documentation

The docs are built with MkDocs and the Material theme, with API pages generated from docstrings by mkdocstrings.

uv sync --extra docs        # or: pip install -e ".[docs]"
mkdocs serve                # live preview at http://127.0.0.1:8000
mkdocs build                # static site into ./site

Building the package

python -m build
twine check dist/*

This produces a source distribution and a wheel in dist/.

Releasing a new version

A version can only be uploaded to PyPI once, so each release needs a new number.

1. Bump the version in two places:
2. pyproject.toml (version = "...")
3. src/pyfilechoose/__init__.py (__version__ = "...")
4. Add a section to CHANGELOG.md.
5. Rebuild from a clean tree:

   rm -rf dist build
   python -m build
   twine check dist/*
   

6. Upload:

   twine upload dist/*
   

7. Tag the release:

   git tag v0.1.1
   git push origin v0.1.1