---
description: Project Structure, Naming Conventions and Tooling
---
## Goal
The project consists of a Python command line application.
This file defines the structure, naming conventions and tooling for test, build, package and manage the dependencies of it.
No functional descriptions are here, just the project's skeleton, rules and housekeeping.
The rules of this file must always be applied.
## Dependency Management and Packaging Toolset
- [Poetry](https://python-poetry.org/) will be used.
## Structure
As a result of using [Poetry](https://python-poetry.org/), this project is organised as follows:
```console
.
├── doc
│ ├── 1-ProblemStatement.md
│ ├── 2-SolutionIntent.md
│ ├── 3-Requirements.md
│ └── 4-Design.md
├── examples
│ ├── 1980-may-15-bday_v2.txt
│ ├── 20250723-filename.txt
│ ├── file_1.txt
│ ├── file-2.txt
│ └── March15_2023-recipe.md
├── src
│ ├── __init__.py
│ ├── llm_renamer.py
│ └── __main__.py
├── test
| ├── func
| └── unit
├── poetry.lock
├── pyproject.toml
├── LICENSE
└── README.md
```
- The [root](../../) folder is represented above by a period (`.`). It contain all the build scripts, configuration files, Python application and package description:
- Poetry's [pyproject.toml](../../pyproject.toml) and [poetry.lock](../../poetry.lock) go here.
- [.gitignore](../../.gitignore), [LICENSE](../../LICENSE) and [README.md](../../README.md) go here.
- The [doc](../../doc/) folder contains all the functional documentation of the project.
- This is not created by Poetry, but by the author of the project.
- Not a comprehensive list: problem statement, solution intent, requirements, design are in this folder.
- The [examples](../../examples/) directory contains examples of the problem to solve.
- This is not created by Poetry, but by the author of the project.
- The funcional test suite to be written in [test](../../test/) must use this files to ensure that the problem is solved and all test pass.
- The directory [src](../../src/) is for Python source code.
- This is part of the structure Poetry expects.
- All the logic goes here.
- The directory [test](../../test/) contains the source code of all the test cases.
- This is part of the stricture Poetry expects.
- At a later point in time we'll get into naming conventions for telling apart unit from functional test cases
## Naming Conventions
- Use [PEP 8](https://peps.python.org/pep-0008/) for the code.
- Use [PEP 257](https://peps.python.org/pep-0257/) for the docstrings.
## Segregation of concerns
- The command-line arguments parsing and validation using [argparse](https://docs.python.org/3/library/argparse.html) are meant to be written in the `main()` function of the entrypoint Python source file.
- This entrypoint is the same to be referenced by the section `[]` of `[pyproject.toml](../../pyproject.toml)`.
- The business logic, or what to do given the command-line arguments, must be written in a different function
- One function per command-line argument or group of arguments that results in a valid invocation.
- As a default behaviour for unrecognised options, there will be a distinct function that outputs an arror message, recommends checking the help options (`-h` or `--help`), and exits with `1`.
## Command-Line Interface
- Use this [GNU Coding Standards](https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html) document for defining the command line switches, options and arguments.
- Use the Python's [argparse](https://docs.python.org/3/library/argparse.html) module to implement them.
## Test Framework
- Use [unittest](https://docs.python.org/3/library/unittest.html) for unit testing.
- Unit tests must only use mocks, using [unittest.mock](https://docs.python.org/3/library/unittest.mock.html). **Do not** use the examples under [examples](../../examples/) for unit testing.
- Use [PyTest](https://docs.pytest.org/en/latest/) for functional testing.
- Use the examples under [examples](../../examples/) for funcional testing.
## Portability and Isolation.
- A virtual environment defined using [Venv](https://docs.python.org/3/library/venv.html) will be used.
- The virtual environment will be using the most recent Python 3 installation found in the `$PATH`.
- **Do not modify the system**'s Python environment.
- Anything needed must be installed within the virtual environment, not in the system.
## License of the Project
[GNU Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) will be the license of this project.
To do so, the following text must be included at the top of every source file of the program, as a Python comment:
```txt
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```
When including the above text as a Python comment:
- Replace `<year>` with 2026: the present year.
- Replace `<name of author>` with the name specified in the `## Author` section of the [README.md](../../README.md) file, and
- Replace `<one line to give the program's name and a brief idea of what it does.>` with the text of the `# Title` header and first sentence under the `# Title` header of the [README.md](../../README.md) file, all in one line.