Skip to content

Align pytask-stata with pytask v0.2. #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 16, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .coveragerc
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
[report]
exclude_lines =
pragma: no cover
if TYPE_CHECKING.*:
\.\.\.
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
9 changes: 0 additions & 9 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 2 additions & 13 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand Down
58 changes: 58 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
@@ -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.
70 changes: 0 additions & 70 deletions CHANGES.rst

This file was deleted.

2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 3 additions & 5 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -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
165 changes: 165 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Loading