Add support for pyproject.toml. (#253)

Author: tobiasraabe

.pre-commit-config.yaml

@@ -40,11 +40,11 @@ repos:
     -   id: pyupgrade
         args: [--py37-plus]
 -   repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v1.20.0
+    rev: v1.20.1
     hooks:
     -   id: setup-cfg-fmt
 -   repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.3.0
     hooks:
     -   id: black
 -   repo: https://github.com/PyCQA/flake8
@@ -68,7 +68,7 @@ repos:
             Pygments,
         ]
 -   repo: https://github.com/PyCQA/doc8
-    rev: 0.10.1
+    rev: 0.11.1
     hooks:
     -   id: doc8
 -   repo: https://github.com/asottile/blacken-docs
@@ -107,7 +107,7 @@ repos:
         ]
         additional_dependencies: [
             attrs>=19.2.0,
-            types-click,
+            click,
             types-setuptools
         ]
         pass_filenames: false

docs/rtd_environment.yml

@@ -20,16 +20,17 @@ dependencies:
   - sphinx-panels
 
   # Package dependencies necessary for sphinx-click
-  - attrs >=17.4.0
+  - attrs >=19.2.0
   - click
   - click-default-group
-  - networkx
+  - networkx >=2.4
   - pluggy
   - pony >=0.7.15
   - pybaum
   - pexpect
   - rich
-  - typing-extensions
+  - tomli >=1.0.0
+  - tomli-w >=1.0.0
 
   - pip:
     - ../

docs/source/changes.md

@@ -34,8 +34,9 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`245` adds choices on the command line to the help pages as metavars and show
   defaults.
 - {pull}`246` formalizes choices for {class}`click.Choice` to {class}`enum.Enum`.
-- {pull}`248` adds a counter at the bottom of the execution table to show how many tasks
+- {pull}`252` adds a counter at the bottom of the execution table to show how many tasks
   have been processed.
+- {pull}`253` adds support for ``pyproject.toml``.
 
 ## 0.1.9 - 2022-02-23
 

docs/source/how_to_guides/bp_parametrizations.md

@@ -26,7 +26,7 @@ First, let us take a look at the folder and file structure of such a project.
 
 ```
 my_project
-├───pytask.ini or tox.ini or setup.cfg
+├───pyproject.toml
 │
 ├───src
 │   └───my_project

docs/source/reference_guides/configuration.md

@@ -1,24 +1,17 @@
 # The configuration
 
-This document lists all options to configure pytask via the configuration files.
+This document lists all options to configure pytask with a `pyproject.toml` file.
 
 ## The basics
 
 To learn about the basics visit the {doc}`tutorial <../tutorials/configuration>`.
 
-## Truthy and falsy values
+Examples for the TOML specification be found [here](https://toml.io/en/) or in [PEP
+518](https://peps.python.org/pep-0518/).
 
-For some of the configuration values you need truthy or falsy values. pytask recognizes
-the following values.
-
-- truthy: `True`, `true`, `1`.
-- falsy: `False`, `false`, `0`.
-
-Additionally, the following values are interpreted as None which is neither truthy or
-falsy.
-
-- `None`
-- `none`
+The configuration values are set under the `[tool.pytask.ini_options]` section to mimic
+the old ini configurations and to allow pytask leveraging the full potential of the TOML
+format in the future.
 
 ## The options
 
@@ -34,7 +27,7 @@ falsy.
     If you have very strong reasons for relying on this inaccuracy, although, it is
     strongly discouraged, you can deactivate the warning in the configuration file with
 
-    .. code-block:: ini
+    .. code-block:: toml
 
         check_casing_of_paths = false
 
@@ -52,31 +45,31 @@ falsy.
     the modules in which tasks are defined. By default, following the link will open the
     module with your default application. It is done with
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        editor_url_scheme = file
+        editor_url_scheme = "file"
 
     If you use ``vscode`` or ``pycharm`` instead, the file will be opened in the
     specified editor and the cursor will also jump to the corresponding line.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        editor_url_scheme = vscode | pycharm
+        editor_url_scheme = "vscode" | "pycharm"
 
     For complete flexibility, you can also enter a custom url which can use the
     variables ``path`` and ``line_number`` to open the file.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        editor_url_scheme = editor://{path}:{line_number}
+        editor_url_scheme = "editor://{path}:{line_number}"
 
     Maybe you want to contribute this URL scheme to make it available to more people.
 
     To disable links, use
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        editor_url_scheme = no_link
+        editor_url_scheme = "no_link"
 
 ```
 
@@ -95,15 +88,13 @@ falsy.
 
     Or, use the configuration file:
 
-    .. code-block:: ini
+    .. code-block:: toml
 
         # For single entries only.
-        ignore = some_file.py
+        ignore = "some_file.py"
 
         # Or single and multiple entries.
-        ignore =
-            some_directory/*
-            some_file.py
+        ignore = ["some_directory/*", "some_file.py"]
 
 ```
 
@@ -123,10 +114,10 @@ falsy.
     silence the warning and document the marker, provide the following information in
     your pytask configuration file.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        markers =
-            wip: Work-in-progress. These are tasks which I am currently working on.
+        [tool.pytask.ini_options.markers]
+        wip = "Work-in-progress. These are tasks which I am currently working on."
 
 ```
 
@@ -143,9 +134,9 @@ falsy.
 
     and in the configuration use
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        n_entries_in_table = all  # default 15
+        n_entries_in_table = "all"  # default 15
 
 ```
 
@@ -156,15 +147,13 @@ falsy.
     command line, you can add the paths to the configuration file. Paths passed via the
     command line will overwrite the configuration value.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
         # For single entries only.
-        paths = src
+        paths = "src"
 
         # Or single and multiple entries.
-        paths =
-            folder_1
-            folder_2/task_2.py
+        paths = ["folder_1", "folder_2/task_2.py"]
 
 ```
 
@@ -180,9 +169,9 @@ falsy.
 
     or use a truthy configuration value.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        pdb = True
+        pdb = true
 
 ```
 
@@ -196,9 +185,9 @@ falsy.
 
         pytask build --show-errors-immediately
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        show_errors_immediately = True
+        show_errors_immediately = true
 
 ```
 
@@ -212,9 +201,9 @@ falsy.
 
         pytask build --show-locals
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        show_locals = True
+        show_locals = true
 
 ```
 
@@ -229,9 +218,9 @@ falsy.
 
     or set the option to a truthy value.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        strict_markers = True
+        strict_markers = true
 
 ```
 
@@ -240,13 +229,11 @@ falsy.
 
     Change the pattern which identify task files.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        task_files = task_*.py  # default
+        task_files = "task_*.py"  # default
 
-        task_files =
-            task_*.py
-            tasks_*.py
+        task_files = ["task_*.py", "tasks_*.py"]
 
 ```
 
@@ -261,7 +248,7 @@ falsy.
 
     or set this option to a truthy value.
 
-    .. code-block:: ini
+    .. code-block:: toml
 
-        trace = True
+        trace = true
 ```

docs/source/tutorials/configuration.md

@@ -1,43 +1,55 @@
 # Configuration
 
 pytask can be configured via the command-line interface or permanently with a
-configuration file.
+`pyproject.toml` file.
 
-## The configuration file
+The file also indicates the root of your project where pytask stores information on
+whether tasks need to be executed or not in a `.pytask.sqlite3` database.
 
-pytask accepts configurations in three files which are `pytask.ini`, `tox.ini` and
-`setup.cfg`. Place a `[pytask]` section in those files and add your configuration below.
+:::{important}
+pytask.ini, tox.ini, and setup.cfg will be deprecated as configuration files for pytask
+starting with v0.3 or v1.0. Switch to a `pyproject.toml` file! If you execute pytask
+with an old configuration file, pytask provides you with a copy-paste snippet of your
+configuration in the `toml` format to facilitate the transition.
+:::
+
+## The configuration file
 
-```ini
-# Content of tox.ini
+You only need to add the header to the configuration file if you want to indicate the
+root of your project.
 
-[pytask]
-ignore =
-    some_path
+```toml
+[tool.pytask.ini_options]
 ```
 
-You can also leave the section empty. It will still have the benefit that pytask has a
-stable root and will store the information about tasks, dependencies, and products in
-the same directory as the configuration file in a database called `.pytask.sqlite3`.
+We can also overwrite pytask's behavior of collecting tasks from the current working
+directory and, instead, search for paths in a directory called `src` next to the
+configuration file.
+
+```toml
+[tool.pytask.ini_options]
+paths = src
+```
 
 ## The location
 
-There are two ways to find the configuration file when invoking pytask.
+There are two ways to point pytask to the configuration file.
 
 First, it is possible to pass the location of the configuration file via
 {option}`pytask build -c` like
 
 ```console
-$ pytask -c config/pytask.ini
+$ pytask -c config/pyproject.toml
 ```
 
-The second option is to let pytask try to find the configuration itself. pytask will
-first look in the current working directory or the common ancestors of multiple paths to
-tasks. It will search for `pytask.ini`, `tox.ini` and `setup.cfg` in this order.
-Whenever a `[pytask]` section is found, the search stops.
+The second option is to let pytask try to find the configuration itself.
 
-If no file is found in the current directory, pytask will climb up the directory tree
-and search in parent directories.
+1. Find the common base directory of all paths passed to pytask (default to the current
+   working directory).
+2. Starting from this directory, look at all parent directories, and return the file if
+   it is found.
+3. If a directory contains a `.git` directory/file, a `.hg` directory or a valid
+   configuration file with the right section stop searching.
 
 ## The options