drytoml 0.1.2

Keep toml configuration centralized and personalizable

drytoml

Keep toml configuration centralized and personalizable.

drytoml enables having .toml files referencing any content from another .toml file. You can reference the whole file, a specific table, or in general anything reachable by a sequence of getitem calls (eg ["tool", "poetry", "source", 0, "url"])

Inspired by flakehell and nitpick, drytoml main motivation is to have several projects share a common, centralized configuration defining codestyles, but still allowing granular control wherever is required.

IMPORTANT: if you want to manually control transclusions and modify files by hand, you should use other tools, like nitpick.

Usage

drytoml has two main usages:

1. Use a file as a reference to create an transcluded one:

   # contents of pyproject.dry.toml
   ...
   [tool.black]
   __extends = "../../common/black.toml"
   target-version = ['py37']
   include = '\.pyi?$'
   include = '\.pyi?$'
   ...
   

   # contents of ../../common/black.toml
   [tool.black]
   line-length = 100
   

   $ dry export --file=pyproject.dry.toml > pyproject.toml
   

   # contents of pyproject.toml
   [tool.black]
   line-length = 100
   target-version = ['py37']
   include = '\.pyi?$'
   

2. Use included wrappers, allowing you to use your current configuration

   Instead of this:

   $ black .
   All done! ✨ 🍰 ✨
   14 files left unchanged.
   

   You would run this

   $ dry black
   reformatted /path/to/cwd/file_with_potentially_long_lines.py
   reformatted /path/to/cwd/another_file_with_potentially_long_lines.py
   All done! ✨ 🍰 ✨
   2 files reformatted, 12 files left unchanged.
   

Transclusion works with relative/absolute paths and urls. Internally drytoml uses tomlkit to merge the corresponding sections between the local and referenced .toml.

For the moment, the following wrappers are supported:

• black
• isort
• flakehell, flake8helled *
• docformatter
• pytest

• NOTE: flakehell project was archived. This requires using a custom fork from here
• NOTE flakehell already implements similar funcionality, using a base key inside [tool.flakehell]

Setup

Install as usual, with `pip`, `poetry`, etc:

Prerequisites

Install

Usage

FAQ

Q: I want to use a different key

A: Use the --key flag (when using dry form cli, or initialize drytoml.parser.Parser using the extend_key kwarg.

Q: I changed a referenced toml upstream (eg in github) but still get the same result.

A: Run dry cache clear --help to see available options.

Contribute

• Use the devcontainer, act command to run github actions locally
• install locally with pip pip install .[dev] or poetry poetry install -E dev

1. Create issue

2. clone

3. Setup Dev environment

   • The easiest way is to use the provided devcontainer inside vscode, which already contains everything pre-installed. You must open the cloned directory using the remote-containers extension. Just run poetry shell or prepend any command with poetry run to ensure commands run inside the virtual environment.

   • Using poetry: poetry install -E dev

   • Using pip (>20 recommended): pip install .[dev]

   The next steps assume you have already activated the venv.

4. Install pre-commit hook (skip if using devcontainer)

   pre-commit install --hook-type commit-msg
   

   • Commits in every branch except those starting with wip/ must be compliant to Conventional Commits.

   • Commit using cz to ensure compliance.

5. Add tests to code

6. Run check(s)

   Useful tip: To debug your code, a useful tool is using drytoml -v explain

   • Manually, executing the check from inside a venv

     For example, to generate the documentation:

     sphinx-apidoc \
       --templatedir=docs/src/templates \
       --separate \
       --module-first \
       --force \
       -o docs/src/apidoc src/drytoml
     

     and then

     sphinx-build docs/src docs/build
     

     See the different checks in .github/workflows

   • Locally with act (Already installed in the devcontainer)

     For example, to emulate a PR run for the docs workflow:

     act -W .github/workflows/docs.yml pull_request
     

   • Remotely, by pushing to an open PR

7. Create PR

TODO

check out current development here