ID Translation Cookiecutter Template

A cookiecutter template backed by my id-translation package.

---

What is it?

A template for a working starting point for creating specialized íd-translation packages for an organization.

Demo project

Sample output available on GitHub.

• 🖥️ Code: demo/bci-id-translation
• 📚 Generated documentation: https://rsundqvist.github.io/id-translation-project/

Quickstart

You will need...

• cookiecutter to generate the project,
• Poetry to install the project, and
• Docker to run the included tests.

Everything else should be installed for when running poetry install. Steps:

1. Generate project

   cookiecutter https://github.com/rsundqvist/id-translation-project.git

2. Start test database (separate window)

   docker run -p 5002:5432 --rm rsundqvist/sakila-preload:postgres

3. Run the included script

   cd <project_slug>
   ./setup-and-verify.sh

The setup-and-generate.sh script will:

1. Lint the generated project (flake8, black, isort)
2. Run the included unit tests against the test database (pytest).
3. Run static type checking (mypy).
4. Generate documentation for the new project (sphinx).

1. Generate the project

Install the latest version of cookiecutter. then generate a new id-translation project.

cookiecutter https://github.com/rsundqvist/id-translation-project.git

Cookiecutter will ask you for a few inputs. You can use the defaults for most of them. The most important ones are listed below.

The keys	What they're used for
organization	Base name used for generated code, as well as some flavor text, e.g. Big Corporation Inc.
namespace	Python namespace for the new package, e.g. from <namespace>.id_translation import translate.
project_slug	The name of the new project, e.g. pip install <namespace>-id-translation.
id_translation_version	Version of the id-translation package.

❗ Subsequent steps will assume that defaults were used for all Cookiecutter prompts.

2. Install the project development environment with Poetry

❗ If you don't have Poetry installed, you can get it here: https://python-poetry.org/docs/#installation

Move into the new project dir, then install and activate the development environment

cd bci-id-translation/  # <--- <project_slug>
poetry install
poetry shell

dev@ubuntu:/git/bci-id-translation$ poetry install
Creating virtualenv bci-id-translation in /git/bci-id-translation/.venv
Installing dependencies from lock file

Package operations: 18 installs, 0 updates, 0 removals

  ...
  • Installing rics (3.0.0)
  • Installing sqlalchemy (2.0.4)
  • Installing id-translation (0.4.0)
  • Installing pg8000 (1.29.4)
  • Installing pytest (7.2.2)

Installing the current project: bci-id-translation (0.1.0)
dev@ubuntu:/git/bci-id-translation$ poetry shell
Spawning shell within /git/bci-id-translation/.venv
dev@ubuntu:/git/bci-id-translation$ . /git/bci-id-translation/.venv/bin/activate
(bci-id-translation-py3.11) dev@ubuntu:/git/bci-id-translation$ 

3. Start the test database for the template project

The pre-configured tests are based on the rsundqvist/sakila-preload:postgres Docker image. From a ❗ new terminal window, run

docker run -p 5002:5432 --rm rsundqvist/sakila-preload:postgres

to start the database on your machine. The container will be removed as soon as the process terminates. See https://hub.docker.com/r/rsundqvist/sakila-preload for more information about this image.

To connect to the database yourself using Python Console, run:

>>> import sqlalchemy
>>> connection_string = "postgresql+pg8000://postgres:Sofia123!@localhost:5002/sakila"
>>> engine = sqlalchemy.create_engine(connection_string)
>>> print(f"Tables for {engine=}:\n" + "\n".join(sorted(sqlalchemy.inspect(engine).get_table_names())))
Tables for engine=Engine(postgresql+pg8000://postgres:***@localhost:5002/sakila):
actor
address
category
city
country
[more tables...]

SQLAlchemy is used internally by the SqlFetcher fetching implementation.

4. Run the included tests

pytest tests/test_basics.py

(bci-id-translation-py3.11) dev@ubuntu:/git/bci-id-translation$ pytest tests/test_basics.py 
====================================================================== test session starts ======================================================================
platform linux -- Python 3.11.2, pytest-7.2.2, pluggy-1.0.0
rootdir: /git/bci-id-translation, configfile: pytest.ini
collected 6 items                                                                                                                                               

tests/test_basics.py ......                                                                                                                               [100%]

======================================================================= 6 passed in 2.98s =======================================================================
(bci-id-translation-py3.11) dev@ubuntu:/git/bci-id-translation$ 

Next steps

Check out the README.md-file of the generated project for more information, or take a peek at the ID Translation project documentation:

• https://id-translation.readthedocs.io/

For an introduction to translation, please see the Translation primer and Interpreting id-translation Logs pages:

• https://id-translation.readthedocs.io/en/stable/documentation/translation-primer.html
• https://id-translation.readthedocs.io/en/stable/documentation/translation-logging.html

Happy translating!

License

MIT