From d284846c37e2f85795ab64006d1120dad27240d4 Mon Sep 17 00:00:00 2001 From: John Reese Date: Tue, 23 Nov 2021 20:24:52 -0800 Subject: [PATCH] Mission statement --- .flake8 | 13 +++++ .github/dependabot.yml | 7 +++ .github/issue_template.md | 11 ++++ .github/pull_request_template.md | 5 ++ .github/workflows/build.yml | 34 ++++++++++++ .gitignore | 2 + CHANGELOG.md | 3 ++ CONTRIBUTING.md | 33 ++++++++++++ README.md | 1 - README.rst | 86 +++++++++++++++++++++++++++++ docs/_static/custom.css | 20 +++++++ docs/_templates/badges.html | 6 +++ docs/_templates/omnilib.html | 24 +++++++++ docs/changelog.rst | 5 ++ docs/conf.py | 92 ++++++++++++++++++++++++++++++++ docs/contributing.rst | 5 ++ docs/index.rst | 9 ++++ makefile | 8 ++- pyproject.toml | 7 ++- requirements-dev.txt | 19 ++++--- requirements.txt | 1 + thx/__init__.py | 4 +- thx/__main__.py | 7 +++ thx/main.py | 20 +++++++ thx/tests/__init__.py | 2 + 25 files changed, 405 insertions(+), 19 deletions(-) create mode 100644 .flake8 create mode 100644 .github/dependabot.yml create mode 100644 .github/issue_template.md create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/build.yml create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/_static/custom.css create mode 100644 docs/_templates/badges.html create mode 100644 docs/_templates/omnilib.html create mode 100644 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/contributing.rst create mode 100644 docs/index.rst create mode 100644 requirements.txt create mode 100644 thx/__main__.py create mode 100644 thx/main.py create mode 100644 thx/tests/__init__.py diff --git a/.flake8 b/.flake8 new file mode 100644 index 0000000..8dad0a3 --- /dev/null +++ b/.flake8 @@ -0,0 +1,13 @@ +[flake8] +ignore = + # mccabe complexity + C901 + + # covered by black/usort + E1 + E2 + E3 + E4 +max-line-length = 88 +per-file-ignores = + __init__.py: F401 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..47511a7 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "monthly" + day: "saturday" \ No newline at end of file diff --git a/.github/issue_template.md b/.github/issue_template.md new file mode 100644 index 0000000..bb23600 --- /dev/null +++ b/.github/issue_template.md @@ -0,0 +1,11 @@ +### Description + + + +### Details + +* OS: +* Python version: +* thx version: +* Can you repro on main? +* Can you repro in a clean virtualenv? diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..1bf3d73 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,5 @@ +### Description + + + +Fixes: # diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..40c67f0 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,34 @@ +name: Build +on: + push: + branches: + - main + tags: + - v* + pull_request: + +jobs: + thx: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"] + os: [macOS-latest, ubuntu-latest, windows-latest] + + steps: + - name: Checkout + uses: actions/checkout@v1 + - name: Set Up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + - name: Install + run: | + python -m pip install --upgrade pip + make setup + pip install -U . + - name: Test + run: make test + - name: Lint + run: make lint diff --git a/.gitignore b/.gitignore index b6e4761..7c4b2f8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +html/ + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d5db7df --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +thx +=== + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a3db07b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing to thx + +## Preparation + +You'll need to have Python 3.6 available for testing. +I recommend using [pyenv][] for this: + + $ pyenv install 3.6.5 + $ pyenv shell 3.6.5 + + +## Setup + +Create a fresh development enviroment, and install the +appropriate tools and dependencies: + + $ cd + $ make venv + $ source .venv/bin/activate + + +## Submitting + +Before submitting a pull request, please ensure +that you have done the following: + +* Documented changes or features in README.md +* Added appropriate license headers to new files +* Written or modified tests for new functionality +* Used `make format` to format code appropriately +* Validated and tested code with `make lint test` + +[pyenv]: https://github.com/pyenv/pyenv diff --git a/README.md b/README.md deleted file mode 100644 index fc8c49e..0000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -# thx \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..672d4aa --- /dev/null +++ b/README.rst @@ -0,0 +1,86 @@ +thx +=== + +A simple, composable command runner for Python projects. + +.. image:: https://img.shields.io/pypi/l/thx.svg + :target: https://github.com/jreese/thx/blob/main/LICENSE + :alt: MIT Licensed +.. image:: https://img.shields.io/pypi/v/thx.svg + :target: https://pypi.org/project/thx + :alt: PyPI Release +.. image:: https://img.shields.io/badge/change-log-blue + :target: https://github.com/jreese/thx/blob/main/CHANGELOG.md + :alt: Changelog +.. image:: https://readthedocs.org/projects/thx/badge/?version=stable + :target: https://thx.readthedocs.io/ + :alt: Documentation Status +.. image:: https://github.com/jreese/thx/workflows/Build/badge.svg + :target: https://github.com/jreese/thx/actions + :alt: Build Status + + +Goals +----- + + "makefiles, but with pyproject.toml" + + -- author + +`thx` should be capable of running one or more commands, configured via simple and +obvious options in the PEP 517 standardized `pyproject.toml`. Commands are simple +strings, or lists of strings, each representing a program to be run, with basic +interpolation of values. + +.. code-block:: toml + + [tool.thx] + default = ["lint", "test"] + module = "thx" + + [tool.thx.commands] + lint = [ + "flake8 {module}", + "ufmt check {module}", + ] + test = "python -m unittest -v {module}.tests" + +With the given configuration, the following commands are possible. Note the automatic +replacement of ``{module}`` with ``thx``: + +.. code-block:: shell-session + + $ thx lint + > flake8 thx + > ufmt check thx + +.. code-block:: shell-session + + $ thx test + > python -m unittest thx.tests + +Without a command, ``thx`` will run the configured list of default commands: + +.. code-block:: shell-session + + $ thx + > flake8 thx + > ufmt check thx + > python -m unittest thx.tests + + +Install +------- + +`thx` is not yet ready for production use. Check the Github repo for development status. + + +License +------- + +`thx` is copyright `John Reese `_, and licensed under +the MIT license. I am providing code in this repository to you under an open +source license. This is my personal repository; the license you receive to my +code is from me and not from my employer. See the `LICENSE`_ file for details. + +.. _LICENSE: https://github.com/jreese/thx/blob/main/LICENSE \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..c376be0 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,20 @@ +div.omnilib { + margin-top: 24px; +} + +div.omnilib-badges { + margin-top: 12px; + margin-bottom: 10px; +} + +div.omnilib-badges a { + color: #bbb; + text-decoration: none; + font-size: 24px; + border: none; +} + +div.omnilib-badges a:hover { + color: #777; + border: none; +} \ No newline at end of file diff --git a/docs/_templates/badges.html b/docs/_templates/badges.html new file mode 100644 index 0000000..6eca18d --- /dev/null +++ b/docs/_templates/badges.html @@ -0,0 +1,6 @@ +
+ Star +
+ + \ No newline at end of file diff --git a/docs/_templates/omnilib.html b/docs/_templates/omnilib.html new file mode 100644 index 0000000..adc4e86 --- /dev/null +++ b/docs/_templates/omnilib.html @@ -0,0 +1,24 @@ +
+

The Omnilib Project

+ + Omnilib is a group of MIT licensed software libraries developed under a + common, inclusive Code of Conduct. + We are committed to providing a welcoming and open space for all contributors who adhere to these rules. + +
+
+ + + +   + + + +   + + + + +
+ + \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..56d6af0 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,5 @@ +Changelog +========= + +.. mdinclude:: ../CHANGELOG.md + :start-line: 2 \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..570ba92 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,92 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +import datetime + +project = "thx" +copyright = f"{datetime.date.today().year}, John Reese" +author = "John Reese" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "m2r", + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +autodoc_default_options = { + "show-inheritance": True, + "members": True, + "undoc-members": True, +} +autodoc_member_order = "groupwise" +autodoc_typehints = "description" + +highlight_language = "python3" +intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} +master_doc = "index" + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "alabaster" +html_theme_options = { + "description": "Pythonic task runner", + "fixed_sidebar": True, + "badge_branch": "main", + "github_button": False, + "github_user": "jreese", + "github_repo": "thx", + "show_powered_by": False, + "sidebar_collapse": False, + "extra_nav_links": { + "Report Issues": "https://github.com/jreese/thx/issues", + }, +} + +html_sidebars = { + "**": [ + "about.html", + "badges.html", + "navigation.html", + "relations.html", + "searchbox.html", + "omnilib.html", + ], +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..89f3c22 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,5 @@ +Contributing +============ + +.. mdinclude:: ../CONTRIBUTING.md + :start-line: 2 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..45679e3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,9 @@ +.. include:: ../README.rst + +.. toctree:: + :hidden: + :maxdepth: 1 + + changelog + contributing + diff --git a/makefile b/makefile index c8b21ca..d616951 100644 --- a/makefile +++ b/makefile @@ -25,15 +25,13 @@ lint: python -m ufmt check $(SRCS) test: - python -m coverage run -m $(SRCS).tests - python -m coverage report - python -m coverage html + python -m unittest -v $(SRCS).tests -html: .venv README.md docs/*.rst docs/conf.py +html: .venv README.rst docs/*.rst docs/conf.py source .venv/bin/activate && sphinx-build -b html docs html clean: - rm -rf build dist README MANIFEST *.egg-info .mypy_cache + rm -rf build dist html *.egg-info .mypy_cache distclean: clean rm -rf .venv diff --git a/pyproject.toml b/pyproject.toml index 1841119..e2a7173 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,9 +6,9 @@ build-backend = "flit_core.buildapi" module = "thx" author = "John Reese" author-email = "john@noswap.com" -description-file = "README.md" +description-file = "README.rst" home-page = "https://github.com/jreese/thx" -requires = [] +requires = ["tomli >= 1.0"] requires-python = ">=3.6" classifiers = [ "Intended Audience :: Developers", @@ -22,6 +22,9 @@ exclude = [ ".github/", ] +[tool.flit.scripts] +thx = "thx.main:main" + [tool.attribution] name = "thx" package = "thx" diff --git a/requirements-dev.txt b/requirements-dev.txt index 2bcba84..583c19b 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,11 +1,10 @@ -attribution==1.5.1 -black==20.8b0 -codecov==2.1.11 -coverage==5.5 -flit==3.0.0 -flake8==3.9.0 -mypy==0.812 -sphinx==3.5.2 -ufmt==1.2 -usort==0.6.2 +attribution==1.5.2 +black==21.11b1 +coverage==6.1.2 +flit==3.5.1 +flake8==4.0.1 +mypy==0.910 +sphinx==4.3.0 +ufmt==1.3.0 +usort==0.6.4 git+https://github.com/miyakogi/m2r@66f4a5a500cdd9fc59085106bff082c9cadafaf3 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..7732473 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +tomli==1.2.2 \ No newline at end of file diff --git a/thx/__init__.py b/thx/__init__.py index e64a082..d77b85e 100644 --- a/thx/__init__.py +++ b/thx/__init__.py @@ -1,4 +1,6 @@ """ -Thanks +Simple, composable command runner for Python projects. """ + +__author__ = "John Reese" from .__version__ import __version__ diff --git a/thx/__main__.py b/thx/__main__.py new file mode 100644 index 0000000..4732797 --- /dev/null +++ b/thx/__main__.py @@ -0,0 +1,7 @@ +# Copyright 2021 John Reese +# Licensed under the MIT License + +from .main import main + +if __name__ == "__main__": + main() diff --git a/thx/main.py b/thx/main.py new file mode 100644 index 0000000..b40d0e8 --- /dev/null +++ b/thx/main.py @@ -0,0 +1,20 @@ +# Copyright 2021 John Reese +# Licensed under the MIT License + +from typing_extensions import Required +import click +from thx import __doc__, __version__ +from typing import Iterable + +@click.group(help=__doc__) +@click.version_option(__version__, "--version", "-V") +def main(): + pass + +@main.command("list") +def list_commands(): + """ + List available commands and exit. + """ + pass + diff --git a/thx/tests/__init__.py b/thx/tests/__init__.py new file mode 100644 index 0000000..d7a1224 --- /dev/null +++ b/thx/tests/__init__.py @@ -0,0 +1,2 @@ +# Copyright 2021 John Reese +# Licensed under the MIT License