pytask-dev · tobiasraabe · Apr 16, 2022 · Mar 21, 2022 · Mar 23, 2022 · Apr 16, 2022
diff --git a/.coveragerc b/.coveragerc
@@ -0,0 +1,5 @@
+[report]
+exclude_lines =
+    pragma: no cover
+    if TYPE_CHECKING.*:
+    \.\.\.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -6,4 +6,4 @@ Provide a description and/or bullet points to describe the changes in this PR.
 
 - [ ] Reference issues which can be closed due to this PR with "Closes #x".
 - [ ] Review whether the documentation needs to be updated.
-- [ ] Document PR in docs/changes.rst.
+- [ ] Document PR in CHANGES.md.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -48,15 +48,6 @@ jobs:
         shell: bash -l {0}
         run: bash <(curl -s https://codecov.io/bash) -F unit -c
 
-      # - name: Run integration tests.
-      #   shell: bash -l {0}
-      #   run: tox -e pytest -- -m integration --cov=./ --cov-report=xml -n auto
-
-      # - name: Upload coverage reports of integration tests.
-      #   if: runner.os == 'Linux' && matrix.python-version == '3.8'
-      #   shell: bash -l {0}
-      #   run: bash <(curl -s https://codecov.io/bash) -F integration -c
-
       - name: Run end-to-end tests.
         shell: bash -l {0}
         run: tox -e pytest -- -m end_to_end --cov=./ --cov-report=xml -n auto

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -23,9 +23,6 @@ repos:
     -   id: python-no-eval
     -   id: python-no-log-warn
     -   id: python-use-type-annotations
-    -   id: rst-backticks
-    -   id: rst-directive-colons
-    -   id: rst-inline-touching-normal
     -   id: text-unicode-replacement-char
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.32.0
@@ -45,11 +42,6 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
--   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black]
 -   repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:
@@ -71,10 +63,6 @@ repos:
             pydocstyle,
             Pygments,
         ]
--   repo: https://github.com/PyCQA/doc8
-    rev: 0.11.1
-    hooks:
-    -   id: doc8
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:
@@ -84,11 +72,12 @@ repos:
   rev: v2.1.0
   hooks:
     -   id: codespell
-        args: [-L unparseable]
 -   repo: https://github.com/mgedmin/check-manifest
     rev: "0.48"
     hooks:
     -   id: check-manifest
+        args: [--no-build-isolation]
+        additional_dependencies: [setuptools-scm, toml]
 -   repo: meta
     hooks:
     -   id: check-hooks-apply

diff --git a/CHANGES.md b/CHANGES.md
@@ -0,0 +1,58 @@
+# Changes
+
+This is a record of all past pytask-stata releases and what went into
+them in reverse chronological order. Releases follow [semantic
+versioning](https://semver.org/) and all releases are available on
+[PyPI](https://pypi.org/project/pytask-stata) and
+[Anaconda.org](https://anaconda.org/conda-forge/pytask-stata).
+
+## 0.2.0 - 2022-xx-xx
+
+-   {pull}`20` removes an unnecessary hook implementation.
+
+## 0.1.2 - 2022-02-08
+
+-   {pull}`19` fixes the minimum python and
+    pytask version.
+
+## 0.1.1 - 2022-02-07
+
+-   {pull}`16` skips concurrent CI builds.
+-   {pull}`17` deprecates Python 3.6 and adds
+    support for Python 3.10.
+
+## 0.1.0 - 2021-07-21
+
+-   {pull}`11` fixes the `README.rst`.
+-   {pull}`13` replaces versioneer with
+    setuptools-scm.
+-   {pull}`14` fixes tests and aligns
+    pytask-stata with pytask v0.1.0.
+
+## 0.0.6 - 2021-03-05
+
+-   {pull}`10` fixes the version of the package.
+
+## 0.0.5 - 2021-03-04
+
+-   {pull}`7` fix some post-release issues.
+-   {pull}`9` adds dependencies to `setup.py`.
+
+## 0.0.4 - 2021-02-25
+
+-   {pull}`6` prepares pytask-stata to be
+    published on PyPI, adds versioneer and more.
+
+## 0.0.3 - 2021-01-16
+
+-   {pull}`4` removes log file handling on UNIX
+    and raises an error if run in parallel.
+
+## 0.0.2 - 2020-10-30
+
+-   {pull}`1` makes pytask-stata work with pytask
+    v0.0.9.
+
+## 0.0.1 - 2020-10-04
+
+-   Release v0.0.1.
diff --git a/CHANGES.rst b/CHANGES.rst
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright 2020-2021 Tobias Raabe
+Copyright 2020 Tobias Raabe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this
 software and associated documentation files (the "Software"), to deal in the Software

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,12 +1,10 @@
-prune .conda
 prune tests
 
-exclude *.rst
+exclude .coveragerc
+exclude *.md
 exclude *.yml
 exclude *.yaml
 exclude tox.ini
 
-include README.rst
+include README.md
 include LICENSE
-include versioneer.py
-include src/pytask_stata/_version.py
diff --git a/README.md b/README.md
@@ -0,0 +1,165 @@
+# pytask-stata
+
+[![PyPI](https://img.shields.io/pypi/v/pytask-stata?color=blue)](https://pypi.org/project/pytask-stata)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytask-stata)](https://pypi.org/project/pytask-stata)
+[![image](https://img.shields.io/conda/vn/conda-forge/pytask-stata.svg)](https://anaconda.org/conda-forge/pytask-stata)
+[![image](https://img.shields.io/conda/pn/conda-forge/pytask-stata.svg)](https://anaconda.org/conda-forge/pytask-stata)
+[![PyPI - License](https://img.shields.io/pypi/l/pytask-stata)](https://pypi.org/project/pytask-stata)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/pytask-stata/main/main)](https://github.com/pytask-dev/pytask-stata/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/pytask-stata/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/pytask-stata)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/pytask-stata/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/pytask-stata/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+------------------------------------------------------------------------
+
+Run Stata\'s do-files with pytask.
+
+## Installation
+
+pytask-stata is available on
+[PyPI](https://pypi.org/project/pytask-stata) and
+[Anaconda.org](https://anaconda.org/conda-forge/pytask-stata). Install
+it with
+
+``` console
+$ pip install pytask-stata
+
+# or
+
+$ conda install -c conda-forge pytask-stata
+```
+
+You also need to have Stata installed on your system and have the
+executable on your system\'s PATH. If you do not know how to do it,
+[here](https://superuser.com/a/284351) is an explanation.
+
+## Usage
+
+Similarly to normal task functions which execute Python code, you define
+tasks to execute scripts written in Stata with Python functions. The
+difference is that the function body does not contain any logic, but the
+decorator tells pytask how to handle the task.
+
+Here is an example where you want to run `script.do`.
+
+``` python
+import pytask
+
+
+@pytask.mark.stata(script="script.do")
+@pytask.mark.produces("auto.dta")
+def task_run_do_file():
+    pass
+```
+
+When executing a do-file, the current working directory changes to the
+directory where the script is located. This allows you, for example, to
+reference every data set you want to read with a relative path from the
+script.
+
+### Dependencies and Products
+
+Dependencies and products can be added as with a normal pytask task
+using the `@pytask.mark.depends_on` and `@pytask.mark.produces`
+decorators. which is explained in this
+[tutorial](https://pytask-dev.readthedocs.io/en/stable/tutorials/defining_dependencies_products.html).
+
+### Accessing dependencies and products in the script
+
+The decorator can be used to pass command line arguments to your Stata
+executable. For example, pass the path of the product with
+
+``` python
+@pytask.mark.stata(script="script.do", options="auto.dta")
+@pytask.mark.produces("auto.dta")
+def task_run_do_file():
+    pass
+```
+
+And in your `script.do`, you can intercept the value with
+
+``` do
+* Intercept command line argument and save to macro named 'produces'.
+args produces
+
+sysuse auto, clear
+save "`produces'"
+```
+
+The relative path inside the do-file works only because the pytask-stata
+switches the current working directory to the directory of the do-file
+before the task is executed.
+
+To make the task independent from the current working directory, pass
+the full path as an command line argument. Here is an example.
+
+``` python
+# Absolute path to the build directory.
+from src.config import BLD
+
+
+@pytask.mark.stata(script="script.do", options=BLD / "auto.dta")
+@pytask.mark.produces(BLD / "auto.dta")
+def task_run_do_file():
+    pass
+```
+
+### Repeating tasks with different scripts or inputs
+
+You can also parametrize the execution of scripts, meaning executing
+multiple do-files as well as passing different command line arguments to
+the same do-file.
+
+The following task executes two do-files which produce different
+outputs.
+
+``` python
+for i in range(2):
+
+    @pytask.mark.task
+    @pytask.mark.stata(script=f"script_{i}.do", options=f"{i}.dta")
+    @pytask.mark.produces(f"{i}.dta")
+    def task_execute_do_file():
+        pass
+```
+
+## Configuration
+
+pytask-stata can be configured with the following options.
+
+*`stata_keep_log`*
+
+Use this option to keep the `.log` files which are produced for
+every task. This option is useful to debug Stata tasks. Set the
+option via the configuration file with
+
+```toml
+[tool.pytask.ini_options]
+stata_keep_log = true
+```
+
+The option is also available in the command line interface via the
+`--stata-keep-log` flag.
+
+
+*`stata_check_log_lines`*
+
+Use this option to vary the number of lines in the log file which
+are checked for error codes. It also controls the number of lines
+displayed on errors. Use any integer greater than zero. Here is the
+entry in the configuration file
+
+```toml
+[tool.pytask.ini_options]
+stata_check_log_lines = 10
+```
+
+and here via the command line interface
+
+``` console
+$ pytask build --stata-check-log-lines 10
+```
+
+## Changes
+
+Consult the [release notes](CHANGES.md) to find out about what is new.