diff --git a/.gitignore b/.gitignore index 78467a3..ad2fbdd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /.tox/ /.pytest_cache/ +/build/ /dist/ /venv/ /.coverage.* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 205b0cf..2d58e90 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -41,16 +41,18 @@ repos: hooks: - id: 'flake8' additional_dependencies: - - 'flake8-bugbear==23.9.16' + - 'flake8-bugbear==23.11.26' - repo: 'https://github.com/editorconfig-checker/editorconfig-checker.python' rev: '2.7.3' hooks: - id: 'editorconfig-checker' + # The README contains YAML that isn't indented using 4 spaces. + exclude: 'README.rst' -# - repo: 'https://github.com/python-jsonschema/check-jsonschema' -# rev: '0.27.1' -# hooks: + - repo: 'https://github.com/python-jsonschema/check-jsonschema' + rev: '0.27.2' + hooks: + - id: 'check-readthedocs' # - id: 'check-dependabot' # - id: 'check-github-workflows' -# - id: 'check-readthedocs' diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml new file mode 100644 index 0000000..1ea82a3 --- /dev/null +++ b/.pre-commit-hooks.yaml @@ -0,0 +1,11 @@ +- description: 'Check file headers are correct using Chipshot.' + id: 'check-headers' + name: 'Chipshot - Check headers' + entry: 'chipshot' + language: 'python' + +- description: 'Update file headers, if needed, using Chipshot.' + id: 'update-headers' + name: 'Chipshot - Update headers' + entry: 'chipshot --update' + language: 'python' diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..1d49f34 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 + +build: + os: 'ubuntu-22.04' + tools: + python: '3.12' + +sphinx: + configuration: 'docs/conf.py' + fail_on_warning: true + +python: + install: + - requirements: 'requirements/docs.txt' diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 3b9d121..bc7a371 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -23,6 +23,36 @@ Please see the fragment files in the `changelog.d directory`_. .. scriv-insert-here +.. _changelog-0.2.0: + +0.2.0 - 2023-11-28 +================== + +Added +----- + +* Add two pre-commit hooks: ``check-headers`` and ``update-headers``. + +Changed +------- + +* Allow template literals in the config file using the ``template`` key. + + Paths to template files can be defined in the ``template_path`` key. + +* When no configuration file is specified, + ``.chipshot.toml`` will be loaded first (if it exists). + + ``pyproject.toml`` will still be loaded as a fallback + if ``.chipshot.toml`` doesn't exist. + +* Rename the ``--debug`` flag to ``--verbose``. + +Documentation +------------- + +* Add initial documentation. + .. _changelog-0.1.0: 0.1.0 - 2023-11-24 diff --git a/README.rst b/README.rst index ae1964d..0d0ce99 100644 --- a/README.rst +++ b/README.rst @@ -26,26 +26,36 @@ but can be configured to support those, too. Sample configuration ==================== -Create a directory that will contain your header template. -For example, the directory might be named ``assets/headers``. +Create a file named ``.chipshot.toml`` with the following content: -Then, create a text file that will contain your header template, -such as ``global.txt``. -You can use ``{{ year }}`` as a stand-in for the current year. - -.. code-block:: text +.. code-block:: toml - Copyright 2021-{{ date }} Developer or Company + [chipshot] + template = """ + Copyright 2021-{{ year }} Developer or Company Released under the terms of the MIT license. SPDX-License-Identifier: MIT + """ -Next, add the following configuration to ``pyproject.toml``: +You can then run ``chipshot path1 path2`` to see what files will be modified. +If you're satisfied, run ``chipshot --update path1 path2`` to update the files. -.. code-block:: toml - [tool.chipshot] - template_root = "assets/headers" - template = "global.txt" +Pre-commit hooks +================ -You can then run ``chipshot path1 path2`` to see what files will be modified. -If you're satisfied, run ``chipshot --update path1 path2`` to update the files. +Chipshot offers two pre-commit hooks to help you manage your projects: + +* ``check-headers`` +* ``update-headers`` + +Here's a sample configuration for ensuring your files have correct headers: + +.. code-block:: yaml + + # .pre-commit-config.yaml + repos: + - repo: 'https://github.com/kurtmckee/chipshot' + rev: 'main' + hooks: + - id: 'update-headers' diff --git a/TODO.rst b/TODO.rst new file mode 100644 index 0000000..3e41ddf --- /dev/null +++ b/TODO.rst @@ -0,0 +1,14 @@ +* add CI +* write documentation +* publish to readthedocs +* catch exceptions and report them +* allow configuring different headers for different file types. + this allows for a license for docs and a license for code +* allow file paths (for example, ``scripts/*`` or ``script-without-suffix``) +* allow custom encodings +* detect encodings using ``.editorconfig`` +* ignore files using ``.gitignore`` +* use multiprocessing for faster work +* update how similarity is calculated + (it doesn't consider all words and reports 100% similarity) +* test against major repos diff --git a/assets/banner.svg b/assets/banner.svg new file mode 100644 index 0000000..6f20d14 --- /dev/null +++ b/assets/banner.svg @@ -0,0 +1,186 @@ + + + +Set up game-winning headers!chipshot diff --git a/assets/headers/global.txt b/assets/headers/global.txt deleted file mode 100644 index 6000b02..0000000 --- a/assets/headers/global.txt +++ /dev/null @@ -1,3 +0,0 @@ -This file is a part of Chipshot -Copyright 2022-{{ year }} Kurt McKee -SPDX-License-Identifier: MIT diff --git a/assets/openmoji-soccer-ball-26BD-2023.svg b/assets/openmoji-soccer-ball-26BD-2023.svg new file mode 100644 index 0000000..7a55b8a --- /dev/null +++ b/assets/openmoji-soccer-ball-26BD-2023.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/banner.png b/docs/_static/banner.png new file mode 100644 index 0000000..89309dd Binary files /dev/null and b/docs/_static/banner.png differ diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..836db48 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,17 @@ +/* + * The CSS code sample comes from: + * https://www.a11yproject.com/posts/how-to-hide-content/ + * + * The CSS selector comes from: + * https://github.com/pallets/pallets-sphinx-themes/blob/1512b53b/src/pallets_sphinx_themes/themes/pocoo/static/pocoo.css#L486-L498 + */ + +.visually-hidden > h1:first-child { + clip: rect(0 0 0 0); + clip-path: inset(50%); + height: 1px; + overflow: hidden; + position: absolute; + white-space: nowrap; + width: 1px; +} diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..f584449 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..ae8cada --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,35 @@ +import pathlib +import tomllib + +# General configuration +# --------------------- + +# The suffix of source filenames. +source_suffix = ".rst" + +# The main toctree document. +master_doc = "index" + +# General information about the project. +project = "Chipshot" +copyright = "2022-2023 Kurt McKee" + +# Extract the project version. +pyproject_ = pathlib.Path(__file__).parent.parent / "pyproject.toml" +info_ = tomllib.loads(pyproject_.read_text()) +version = release = info_["tool"]["poetry"]["version"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + + +# HTML theme configuration +# ------------------------ + +html_theme = "alabaster" +html_static_path = [ + "_static", +] +html_theme_options = { + "logo": "logo.png", +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..570260d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,78 @@ +.. rst-class:: visually-hidden + +Welcome to the Chipshot documentation +##################################### + +.. image:: _static/banner.png + :alt: The Chipshot logo, with a soccer ball shooting up and away from the project name. + +Chipshot helps you standardize headers in your source code. +Its aim is to help ensure that all source files have excellent headers +with accurate copyright and license information. +If it can help you achieve your goals, then it will have done its job! + +Example +======= + +Chipshot respects byte order marks, newlines, and document prologues +(like hashbangs and XML declarations) when adding and updating headers. +Its default configuration supports many different file types +so it's easy to get started with a minimal configuration file. + +.. rubric:: ``.chipshot.toml`` +.. code-block:: toml + + [chipshot] + template = """ + Copyright 2022-{{ year }} Company Name + SPDX-License-Identifier: MIT + """ + +Headers will be rendered as comments based on the file extension. + +.. rubric:: Python +.. code-block:: python + + # Copyright 2022-2023 Company Name + # SPDX-License-Identifier: MIT + +.. rubric:: C +.. code-block:: c + + /* + * Copyright 2022-2023 Company Name + * SPDX-License-Identifier: MIT + */ + + +Getting Started +=============== + +.. toctree:: + :maxdepth: 1 + + tutorial/overview + tutorial/installing + tutorial/configuring + +* Default comment styles gallery + + +How-To Guides +============= + +* How to customize comment styles +* How to integrate Chipshot in your everyday development + + +Reference +========= + +.. toctree:: + :maxdepth: 1 + + reference/boms + +* Configuration file format +* Pre-commit hooks +* CLI options diff --git a/docs/reference/boms.rst b/docs/reference/boms.rst new file mode 100644 index 0000000..216e217 --- /dev/null +++ b/docs/reference/boms.rst @@ -0,0 +1,25 @@ +Byte Order Marks (BOMs) +####################### + +Chipshot initially reads all files as binary. +If the first bytes correspond to a known byte order mark (BOM), +Chipshot will decode the file using the encoding scheme indicated by the BOM. + +The encoding associated with the BOM is always respected, +even if Chipshot is configured to expect a different encoding. +If the file cannot be decoded using the BOM-indicated encoding, +Chipshot will not try to use any other encoding. + +If Chipshot updates the file, the BOM will be retained. + +These are the BOMs that Chipshot understands, +and the associated encoding that will be used if a BOM is encountered. + +.. csv-table:: + :header: "BOM characters", "Encoding" + + "``00 00 fe ff``", "UTF-32 (Big Endian)" + "``ff fe 00 00``", "UTF-32 (Little Endian)" + "``fe ff``", "UTF-16 (Big Endian)" + "``ff fe``", "UTF-16 (Little Endian)" + "``ef bb bf``", "UTF-8" diff --git a/docs/tutorial/configuring.rst b/docs/tutorial/configuring.rst new file mode 100644 index 0000000..10eb4fb --- /dev/null +++ b/docs/tutorial/configuring.rst @@ -0,0 +1,47 @@ +Configuring Chipshot +#################### + +Chipshot needs to know what header text to put at the tops of your files. +This is configured in one of two files by default: + +* ``.chipshot.toml`` +* ``pyproject.toml`` + +This section of the documentation will show you +how to configure Chipshot using ``.chipshot.toml``. + + +Header Templates +================ + +Open your favorite text editor and put this text into it: + +.. code-block:: toml + + [chipshot] + template = """ + Copyright {{ year }} Developer + """ + +Save the file as ``.chipshot.toml``. +Then, at the command line, run Chipshot +and pass a directory containing source code files as the first argument. +By default, Chipshot won't update any files; +it will simply tell you what it believes it should do with the file. + +.. code-block:: console + + $ chipshot src/ + INFO: src/no_header.py: Adding header (no original header found) + INFO: src/has_comments_but_no_header.py: Adding header (29.46% similarity) + INFO: src/has_header_with_different_email.py: Updating header (96.46% similarity) + +If the output looks correct to you, +add the ``--update`` flag to have Chipshot make changes to the files. + +.. code-block:: console + + $ chipshot --update src/ + INFO: src/no_header.py: Adding header (no original header found) + INFO: src/has_comments_but_no_header.py: Adding header (29.46% similarity) + INFO: src/has_header_with_different_email.py: Updating header (96.46% similarity) diff --git a/docs/tutorial/installing.rst b/docs/tutorial/installing.rst new file mode 100644 index 0000000..159c890 --- /dev/null +++ b/docs/tutorial/installing.rst @@ -0,0 +1,71 @@ +Installing Chipshot +################### + +Chipshot is published to the Python Package Index (PyPI). +If you have a preferred way to install Python packages, +feel free to use that method. + + +pipx +==== + +`pipx`_ is an excellent way to install Python applications. +If you already have pipx installed on your system, +you can use it to install Chipshot. + +.. code-block:: console + + $ pipx install chipshot + $ chipshot --version + + +pip +=== + +If you have Python installed, then you have pip installed. +However, you should avoid installing Chipshot into your system Python's packages. + +There are two methods you can follow: + +#. Create a virtual environment +#. Install Chipshot in your Python user packages + +The virtual environment method is preferable +because it will help isolate Chipshot's Python dependencies +and reduce the possibility of a conflict in dependency versions, +but you will have to activate the virtual environment +each time you want to use Chipshot. + +Virtual Environment Method +-------------------------- + +.. rubric:: Linux/macOS +.. code-block:: console + + $ python -m venv venv + $ . venv/bin/activate + (venv) $ python -m pip install chipshot + (venv) $ chipshot --version + +.. rubric:: Windows +.. code-block:: doscon + + C:\Users\Me> python -m venv venv + C:\Users\Me> venv\Scripts\activate.bat + (venv) C:\Users\Me> python -m pip install chipshot + (venv) C:\Users\Me> chipshot --version + +Python User Directory Method +---------------------------- + +.. rubric:: Linux/macOS/Windows +.. code-block:: console + + $ python -m pip install --user chipshot + $ chipshot --version + + +.. Links +.. ----- +.. +.. _pipx: https://pypa.github.io/pipx/ diff --git a/docs/tutorial/overview.rst b/docs/tutorial/overview.rst new file mode 100644 index 0000000..cb499b1 --- /dev/null +++ b/docs/tutorial/overview.rst @@ -0,0 +1,162 @@ +An overview of Chipshot's features +################################## + +Chipshot helps ensure source code headers are consistent. +You tell it what the header text should be using a *template*, +and it will render the header as a comment based on the file extension. + +Not all file formats use the same types of comment styles or conventions, +so Chipshot works to respect: + +* :ref:`comment-styles` +* :ref:`prologues` +* :ref:`boms` +* :ref:`newlines` + +In addition, Chipshot is flexible, and supports a great deal of customization: + +* `multiple-templates` +* :ref:`custom-styles` + + +Throughout this overview, the following header template will be used: + +.. code-block:: text + + Copyright 2022-{{ year }} Company Name + Licensed under the terms of the MIT license. + +Note that ``{{ year }}`` will be rendered as ``2023`` in this document. + + +.. _comment-styles: + +Comment styles +============== + +Different programming and markup languages have different comment styles. +Here is a small sample of comment styles that Chipshot supports by default. + +.. rubric:: Python +.. code-block:: python + + # Copyright 2022-2023 Company Name + # Licensed under the terms of the MIT license. + +.. rubric:: ReStructuredText +.. code-block:: rst + + .. + Copyright 2022-2023 Company Name + Licensed under the terms of the MIT license. + +.. rubric:: SQL +.. code-block:: sql + + -- Copyright 2022-2023 Company Name + -- Licensed under the terms of the MIT license. + +.. rubric:: XML +.. code-block:: xml + + + + +.. _prologues: + +Document Prologues +================== + +Some files have mandatory *prologues* -- content that MUST appear on the first line or lines. +For example, many executable script files must start with a hashbang line +so the operating system knows how to execute the file. + +If Chipshot finds a hashbang in a file format that supports it, +Chipshot will always add or update headers after the hashbang: + +.. rubric:: Example: A hashbang in a NodeJS shell script +.. code-block:: js + + #!/usr/bin/env node + + // Copyright 2022-2023 Company Name + // Licensed under the terms of the MIT license. + + console.log("Hello, World!"); + +Executable scripts aren't the only place where the first line is important; +XML requires declarations to appear before comments, too. + +.. rubric:: Example: An XML declaration +.. code-block:: xml + + + + + + +.. _boms: + +Unicode Byte Order Marks +======================== + +Some programming languages and file formats rely on Unicode byte order marks (BOMs) +to enable Unicode features. For example, AutoHotkey relies on UTF-8 BOMs +to indicate when it should switch from ANSI to Unicode. + +When Chipshot encounters a byte order mark in a file +it will always decode the file using the encoding indicated by the BOM. +If Chipshot adds or updates a header, +it will always retain the original BOM. + +.. note:: + + Chipshot does not add nor remove BOMs; + it only retains existing BOMs. + + +.. _newlines: + +Newlines +======== + +Different files in your repository may use different newline styles. +When Chipshot updates headers, it respects each file's existing newline style. + +.. note:: + + Chipshot does not standardize newlines; + it only retains the existing newline style. + + +.. _custom-styles: + +Custom Styles +============= + +Chipshot allows custom comment styles, +so it's possible to add new styles as needed. + +.. rubric:: Example: A custom style in ``.chipshot.toml`` for PHP scripts +.. code-block:: toml + + [chipshot.extension.php] + block_prefix = "" + +This will result in a header rendered like this: + +.. rubric:: Example: A rendered PHP header +.. code-block:: php + + diff --git a/poetry.lock b/poetry.lock index 8e90868..d560d6f 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,5 +1,143 @@ # This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand. +[[package]] +name = "alabaster" +version = "0.7.13" +description = "A configurable sidebar-enabled Sphinx theme" +optional = false +python-versions = ">=3.6" +files = [ + {file = "alabaster-0.7.13-py3-none-any.whl", hash = "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3"}, + {file = "alabaster-0.7.13.tar.gz", hash = "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2"}, +] + +[[package]] +name = "babel" +version = "2.13.1" +description = "Internationalization utilities" +optional = false +python-versions = ">=3.7" +files = [ + {file = "Babel-2.13.1-py3-none-any.whl", hash = "sha256:7077a4984b02b6727ac10f1f7294484f737443d7e2e66c5e4380e41a3ae0b4ed"}, + {file = "Babel-2.13.1.tar.gz", hash = "sha256:33e0952d7dd6374af8dbf6768cc4ddf3ccfefc244f9986d4074704f2fbd18900"}, +] + +[package.dependencies] +setuptools = {version = "*", markers = "python_version >= \"3.12\""} + +[package.extras] +dev = ["freezegun (>=1.0,<2.0)", "pytest (>=6.0)", "pytest-cov"] + +[[package]] +name = "certifi" +version = "2023.11.17" +description = "Python package for providing Mozilla's CA Bundle." +optional = false +python-versions = ">=3.6" +files = [ + {file = "certifi-2023.11.17-py3-none-any.whl", hash = "sha256:e036ab49d5b79556f99cfc2d9320b34cfbe5be05c5871b51de9329f0603b0474"}, + {file = "certifi-2023.11.17.tar.gz", hash = "sha256:9b469f3a900bf28dc19b8cfbf8019bf47f7fdd1a65a1d4ffb98fc14166beb4d1"}, +] + +[[package]] +name = "charset-normalizer" +version = "3.3.2" +description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet." +optional = false +python-versions = ">=3.7.0" +files = [ + {file = "charset-normalizer-3.3.2.tar.gz", hash = "sha256:f30c3cb33b24454a82faecaf01b19c18562b1e89558fb6c56de4d9118a032fd5"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:25baf083bf6f6b341f4121c2f3c548875ee6f5339300e08be3f2b2ba1721cdd3"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:06435b539f889b1f6f4ac1758871aae42dc3a8c0e24ac9e60c2384973ad73027"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9063e24fdb1e498ab71cb7419e24622516c4a04476b17a2dab57e8baa30d6e03"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6897af51655e3691ff853668779c7bad41579facacf5fd7253b0133308cf000d"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1d3193f4a680c64b4b6a9115943538edb896edc190f0b222e73761716519268e"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cd70574b12bb8a4d2aaa0094515df2463cb429d8536cfb6c7ce983246983e5a6"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8465322196c8b4d7ab6d1e049e4c5cb460d0394da4a27d23cc242fbf0034b6b5"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a9a8e9031d613fd2009c182b69c7b2c1ef8239a0efb1df3f7c8da66d5dd3d537"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:beb58fe5cdb101e3a055192ac291b7a21e3b7ef4f67fa1d74e331a7f2124341c"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:e06ed3eb3218bc64786f7db41917d4e686cc4856944f53d5bdf83a6884432e12"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_ppc64le.whl", hash = "sha256:2e81c7b9c8979ce92ed306c249d46894776a909505d8f5a4ba55b14206e3222f"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_s390x.whl", hash = "sha256:572c3763a264ba47b3cf708a44ce965d98555f618ca42c926a9c1616d8f34269"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:fd1abc0d89e30cc4e02e4064dc67fcc51bd941eb395c502aac3ec19fab46b519"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-win32.whl", hash = "sha256:3d47fa203a7bd9c5b6cee4736ee84ca03b8ef23193c0d1ca99b5089f72645c73"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-win_amd64.whl", hash = "sha256:10955842570876604d404661fbccbc9c7e684caf432c09c715ec38fbae45ae09"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:802fe99cca7457642125a8a88a084cef28ff0cf9407060f7b93dca5aa25480db"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:573f6eac48f4769d667c4442081b1794f52919e7edada77495aaed9236d13a96"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:549a3a73da901d5bc3ce8d24e0600d1fa85524c10287f6004fbab87672bf3e1e"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f27273b60488abe721a075bcca6d7f3964f9f6f067c8c4c605743023d7d3944f"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1ceae2f17a9c33cb48e3263960dc5fc8005351ee19db217e9b1bb15d28c02574"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:65f6f63034100ead094b8744b3b97965785388f308a64cf8d7c34f2f2e5be0c4"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:753f10e867343b4511128c6ed8c82f7bec3bd026875576dfd88483c5c73b2fd8"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4a78b2b446bd7c934f5dcedc588903fb2f5eec172f3d29e52a9096a43722adfc"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:e537484df0d8f426ce2afb2d0f8e1c3d0b114b83f8850e5f2fbea0e797bd82ae"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:eb6904c354526e758fda7167b33005998fb68c46fbc10e013ca97f21ca5c8887"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-musllinux_1_1_ppc64le.whl", hash = "sha256:deb6be0ac38ece9ba87dea880e438f25ca3eddfac8b002a2ec3d9183a454e8ae"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-musllinux_1_1_s390x.whl", hash = "sha256:4ab2fe47fae9e0f9dee8c04187ce5d09f48eabe611be8259444906793ab7cbce"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:80402cd6ee291dcb72644d6eac93785fe2c8b9cb30893c1af5b8fdd753b9d40f"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-win32.whl", hash = "sha256:7cd13a2e3ddeed6913a65e66e94b51d80a041145a026c27e6bb76c31a853c6ab"}, + {file = "charset_normalizer-3.3.2-cp311-cp311-win_amd64.whl", hash = "sha256:663946639d296df6a2bb2aa51b60a2454ca1cb29835324c640dafb5ff2131a77"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:0b2b64d2bb6d3fb9112bafa732def486049e63de9618b5843bcdd081d8144cd8"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:ddbb2551d7e0102e7252db79ba445cdab71b26640817ab1e3e3648dad515003b"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:55086ee1064215781fff39a1af09518bc9255b50d6333f2e4c74ca09fac6a8f6"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8f4a014bc36d3c57402e2977dada34f9c12300af536839dc38c0beab8878f38a"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a10af20b82360ab00827f916a6058451b723b4e65030c5a18577c8b2de5b3389"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8d756e44e94489e49571086ef83b2bb8ce311e730092d2c34ca8f7d925cb20aa"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:90d558489962fd4918143277a773316e56c72da56ec7aa3dc3dbbe20fdfed15b"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:6ac7ffc7ad6d040517be39eb591cac5ff87416c2537df6ba3cba3bae290c0fed"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:7ed9e526742851e8d5cc9e6cf41427dfc6068d4f5a3bb03659444b4cabf6bc26"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:8bdb58ff7ba23002a4c5808d608e4e6c687175724f54a5dade5fa8c67b604e4d"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-musllinux_1_1_ppc64le.whl", hash = "sha256:6b3251890fff30ee142c44144871185dbe13b11bab478a88887a639655be1068"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-musllinux_1_1_s390x.whl", hash = "sha256:b4a23f61ce87adf89be746c8a8974fe1c823c891d8f86eb218bb957c924bb143"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:efcb3f6676480691518c177e3b465bcddf57cea040302f9f4e6e191af91174d4"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-win32.whl", hash = "sha256:d965bba47ddeec8cd560687584e88cf699fd28f192ceb452d1d7ee807c5597b7"}, + {file = "charset_normalizer-3.3.2-cp312-cp312-win_amd64.whl", hash = "sha256:96b02a3dc4381e5494fad39be677abcb5e6634bf7b4fa83a6dd3112607547001"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:95f2a5796329323b8f0512e09dbb7a1860c46a39da62ecb2324f116fa8fdc85c"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c002b4ffc0be611f0d9da932eb0f704fe2602a9a949d1f738e4c34c75b0863d5"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a981a536974bbc7a512cf44ed14938cf01030a99e9b3a06dd59578882f06f985"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3287761bc4ee9e33561a7e058c72ac0938c4f57fe49a09eae428fd88aafe7bb6"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:42cb296636fcc8b0644486d15c12376cb9fa75443e00fb25de0b8602e64c1714"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0a55554a2fa0d408816b3b5cedf0045f4b8e1a6065aec45849de2d6f3f8e9786"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:c083af607d2515612056a31f0a8d9e0fcb5876b7bfc0abad3ecd275bc4ebc2d5"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:87d1351268731db79e0f8e745d92493ee2841c974128ef629dc518b937d9194c"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-musllinux_1_1_ppc64le.whl", hash = "sha256:bd8f7df7d12c2db9fab40bdd87a7c09b1530128315d047a086fa3ae3435cb3a8"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-musllinux_1_1_s390x.whl", hash = "sha256:c180f51afb394e165eafe4ac2936a14bee3eb10debc9d9e4db8958fe36afe711"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:8c622a5fe39a48f78944a87d4fb8a53ee07344641b0562c540d840748571b811"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-win32.whl", hash = "sha256:db364eca23f876da6f9e16c9da0df51aa4f104a972735574842618b8c6d999d4"}, + {file = "charset_normalizer-3.3.2-cp37-cp37m-win_amd64.whl", hash = "sha256:86216b5cee4b06df986d214f664305142d9c76df9b6512be2738aa72a2048f99"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:6463effa3186ea09411d50efc7d85360b38d5f09b870c48e4600f63af490e56a"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:6c4caeef8fa63d06bd437cd4bdcf3ffefe6738fb1b25951440d80dc7df8c03ac"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:37e55c8e51c236f95b033f6fb391d7d7970ba5fe7ff453dad675e88cf303377a"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fb69256e180cb6c8a894fee62b3afebae785babc1ee98b81cdf68bbca1987f33"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ae5f4161f18c61806f411a13b0310bea87f987c7d2ecdbdaad0e94eb2e404238"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b2b0a0c0517616b6869869f8c581d4eb2dd83a4d79e0ebcb7d373ef9956aeb0a"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:45485e01ff4d3630ec0d9617310448a8702f70e9c01906b0d0118bdf9d124cf2"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:eb00ed941194665c332bf8e078baf037d6c35d7c4f3102ea2d4f16ca94a26dc8"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:2127566c664442652f024c837091890cb1942c30937add288223dc895793f898"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:a50aebfa173e157099939b17f18600f72f84eed3049e743b68ad15bd69b6bf99"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-musllinux_1_1_ppc64le.whl", hash = "sha256:4d0d1650369165a14e14e1e47b372cfcb31d6ab44e6e33cb2d4e57265290044d"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-musllinux_1_1_s390x.whl", hash = "sha256:923c0c831b7cfcb071580d3f46c4baf50f174be571576556269530f4bbd79d04"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:06a81e93cd441c56a9b65d8e1d043daeb97a3d0856d177d5c90ba85acb3db087"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-win32.whl", hash = "sha256:6ef1d82a3af9d3eecdba2321dc1b3c238245d890843e040e41e470ffa64c3e25"}, + {file = "charset_normalizer-3.3.2-cp38-cp38-win_amd64.whl", hash = "sha256:eb8821e09e916165e160797a6c17edda0679379a4be5c716c260e836e122f54b"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:c235ebd9baae02f1b77bcea61bce332cb4331dc3617d254df3323aa01ab47bd4"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:5b4c145409bef602a690e7cfad0a15a55c13320ff7a3ad7ca59c13bb8ba4d45d"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:68d1f8a9e9e37c1223b656399be5d6b448dea850bed7d0f87a8311f1ff3dabb0"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:22afcb9f253dac0696b5a4be4a1c0f8762f8239e21b99680099abd9b2b1b2269"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e27ad930a842b4c5eb8ac0016b0a54f5aebbe679340c26101df33424142c143c"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1f79682fbe303db92bc2b1136016a38a42e835d932bab5b3b1bfcfbf0640e519"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b261ccdec7821281dade748d088bb6e9b69e6d15b30652b74cbbac25e280b796"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:122c7fa62b130ed55f8f285bfd56d5f4b4a5b503609d181f9ad85e55c89f4185"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:d0eccceffcb53201b5bfebb52600a5fb483a20b61da9dbc885f8b103cbe7598c"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:9f96df6923e21816da7e0ad3fd47dd8f94b2a5ce594e00677c0013018b813458"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-musllinux_1_1_ppc64le.whl", hash = "sha256:7f04c839ed0b6b98b1a7501a002144b76c18fb1c1850c8b98d458ac269e26ed2"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-musllinux_1_1_s390x.whl", hash = "sha256:34d1c8da1e78d2e001f363791c98a272bb734000fcef47a491c1e3b0505657a8"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:ff8fa367d09b717b2a17a052544193ad76cd49979c805768879cb63d9ca50561"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-win32.whl", hash = "sha256:aed38f6e4fb3f5d6bf81bfa990a07806be9d83cf7bacef998ab1a9bd660a581f"}, + {file = "charset_normalizer-3.3.2-cp39-cp39-win_amd64.whl", hash = "sha256:b01b88d45a6fcb69667cd6d2f7a9aeb4bf53760d7fc536bf679ec94fe9f3ff3d"}, + {file = "charset_normalizer-3.3.2-py3-none-any.whl", hash = "sha256:3e4d1f6587322d2788836a99c69062fbb091331ec940e02d12d179c1d53e25fc"}, +] + [[package]] name = "click" version = "8.1.7" @@ -92,6 +230,17 @@ tomli = {version = "*", optional = true, markers = "python_full_version <= \"3.1 [package.extras] toml = ["tomli"] +[[package]] +name = "docutils" +version = "0.20.1" +description = "Docutils -- Python Documentation Utilities" +optional = false +python-versions = ">=3.7" +files = [ + {file = "docutils-0.20.1-py3-none-any.whl", hash = "sha256:96f387a2c5562db4476f09f13bbab2192e764cac08ebbf3a34a95d9b1e4a59d6"}, + {file = "docutils-0.20.1.tar.gz", hash = "sha256:f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b"}, +] + [[package]] name = "exceptiongroup" version = "1.2.0" @@ -106,6 +255,28 @@ files = [ [package.extras] test = ["pytest (>=6)"] +[[package]] +name = "idna" +version = "3.6" +description = "Internationalized Domain Names in Applications (IDNA)" +optional = false +python-versions = ">=3.5" +files = [ + {file = "idna-3.6-py3-none-any.whl", hash = "sha256:c05567e9c24a6b9faaa835c4821bad0590fbb9d5779e7caa6e1cc4978e7eb24f"}, + {file = "idna-3.6.tar.gz", hash = "sha256:9ecdbbd083b06798ae1e86adcbfe8ab1479cf864e4ee30fe4e46a003d12491ca"}, +] + +[[package]] +name = "imagesize" +version = "1.4.1" +description = "Getting image size from png/jpeg/jpeg2000/gif file" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +files = [ + {file = "imagesize-1.4.1-py2.py3-none-any.whl", hash = "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b"}, + {file = "imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a"}, +] + [[package]] name = "importlib-metadata" version = "6.8.0" @@ -325,6 +496,21 @@ files = [ {file = "pyfakefs-5.3.1.tar.gz", hash = "sha256:dd1fb374039fadccf35d3f3df7aa5d239482e0650dcd240e053d3b9e78740918"}, ] +[[package]] +name = "pygments" +version = "2.17.2" +description = "Pygments is a syntax highlighting package written in Python." +optional = false +python-versions = ">=3.7" +files = [ + {file = "pygments-2.17.2-py3-none-any.whl", hash = "sha256:b27c2826c47d0f3219f29554824c30c5e8945175d888647acd804ddd04af846c"}, + {file = "pygments-2.17.2.tar.gz", hash = "sha256:da46cec9fd2de5be3a8a784f434e4c4ab670b4ff54d605c4c2717e9d49c4c367"}, +] + +[package.extras] +plugins = ["importlib-metadata"] +windows-terminal = ["colorama (>=0.4.6)"] + [[package]] name = "pytest" version = "7.4.3" @@ -362,6 +548,192 @@ files = [ importlib-metadata = {version = ">=3.6.0", markers = "python_version < \"3.10\""} pytest = "*" +[[package]] +name = "requests" +version = "2.31.0" +description = "Python HTTP for Humans." +optional = false +python-versions = ">=3.7" +files = [ + {file = "requests-2.31.0-py3-none-any.whl", hash = "sha256:58cd2187c01e70e6e26505bca751777aa9f2ee0b7f4300988b709f44e013003f"}, + {file = "requests-2.31.0.tar.gz", hash = "sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e1"}, +] + +[package.dependencies] +certifi = ">=2017.4.17" +charset-normalizer = ">=2,<4" +idna = ">=2.5,<4" +urllib3 = ">=1.21.1,<3" + +[package.extras] +socks = ["PySocks (>=1.5.6,!=1.5.7)"] +use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"] + +[[package]] +name = "setuptools" +version = "69.0.2" +description = "Easily download, build, install, upgrade, and uninstall Python packages" +optional = false +python-versions = ">=3.8" +files = [ + {file = "setuptools-69.0.2-py3-none-any.whl", hash = "sha256:1e8fdff6797d3865f37397be788a4e3cba233608e9b509382a2777d25ebde7f2"}, + {file = "setuptools-69.0.2.tar.gz", hash = "sha256:735896e78a4742605974de002ac60562d286fa8051a7e2299445e8e8fbb01aa6"}, +] + +[package.extras] +docs = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "pygments-github-lexers (==0.0.5)", "rst.linker (>=1.9)", "sphinx (<7.2.5)", "sphinx (>=3.5)", "sphinx-favicon", "sphinx-inline-tabs", "sphinx-lint", "sphinx-notfound-page (>=1,<2)", "sphinx-reredirects", "sphinxcontrib-towncrier"] +testing = ["build[virtualenv]", "filelock (>=3.4.0)", "flake8-2020", "ini2toml[lite] (>=0.9)", "jaraco.develop (>=7.21)", "jaraco.envs (>=2.2)", "jaraco.path (>=3.2.0)", "pip (>=19.1)", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-mypy (>=0.9.1)", "pytest-perf", "pytest-ruff", "pytest-timeout", "pytest-xdist", "tomli-w (>=1.0.0)", "virtualenv (>=13.0.0)", "wheel"] +testing-integration = ["build[virtualenv] (>=1.0.3)", "filelock (>=3.4.0)", "jaraco.envs (>=2.2)", "jaraco.path (>=3.2.0)", "packaging (>=23.1)", "pytest", "pytest-enabler", "pytest-xdist", "tomli", "virtualenv (>=13.0.0)", "wheel"] + +[[package]] +name = "snowballstemmer" +version = "2.2.0" +description = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms." +optional = false +python-versions = "*" +files = [ + {file = "snowballstemmer-2.2.0-py2.py3-none-any.whl", hash = "sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a"}, + {file = "snowballstemmer-2.2.0.tar.gz", hash = "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1"}, +] + +[[package]] +name = "sphinx" +version = "7.2.6" +description = "Python documentation generator" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinx-7.2.6-py3-none-any.whl", hash = "sha256:1e09160a40b956dc623c910118fa636da93bd3ca0b9876a7b3df90f07d691560"}, + {file = "sphinx-7.2.6.tar.gz", hash = "sha256:9a5160e1ea90688d5963ba09a2dcd8bdd526620edbb65c328728f1b2228d5ab5"}, +] + +[package.dependencies] +alabaster = ">=0.7,<0.8" +babel = ">=2.9" +colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""} +docutils = ">=0.18.1,<0.21" +imagesize = ">=1.3" +Jinja2 = ">=3.0" +packaging = ">=21.0" +Pygments = ">=2.14" +requests = ">=2.25.0" +snowballstemmer = ">=2.0" +sphinxcontrib-applehelp = "*" +sphinxcontrib-devhelp = "*" +sphinxcontrib-htmlhelp = ">=2.0.0" +sphinxcontrib-jsmath = "*" +sphinxcontrib-qthelp = "*" +sphinxcontrib-serializinghtml = ">=1.1.9" + +[package.extras] +docs = ["sphinxcontrib-websupport"] +lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-simplify", "isort", "mypy (>=0.990)", "ruff", "sphinx-lint", "types-requests"] +test = ["cython (>=3.0)", "filelock", "html5lib", "pytest (>=4.6)", "setuptools (>=67.0)"] + +[[package]] +name = "sphinxcontrib-applehelp" +version = "1.0.7" +description = "sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinxcontrib_applehelp-1.0.7-py3-none-any.whl", hash = "sha256:094c4d56209d1734e7d252f6e0b3ccc090bd52ee56807a5d9315b19c122ab15d"}, + {file = "sphinxcontrib_applehelp-1.0.7.tar.gz", hash = "sha256:39fdc8d762d33b01a7d8f026a3b7d71563ea3b72787d5f00ad8465bd9d6dfbfa"}, +] + +[package.dependencies] +Sphinx = ">=5" + +[package.extras] +lint = ["docutils-stubs", "flake8", "mypy"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-devhelp" +version = "1.0.5" +description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp documents" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinxcontrib_devhelp-1.0.5-py3-none-any.whl", hash = "sha256:fe8009aed765188f08fcaadbb3ea0d90ce8ae2d76710b7e29ea7d047177dae2f"}, + {file = "sphinxcontrib_devhelp-1.0.5.tar.gz", hash = "sha256:63b41e0d38207ca40ebbeabcf4d8e51f76c03e78cd61abe118cf4435c73d4212"}, +] + +[package.dependencies] +Sphinx = ">=5" + +[package.extras] +lint = ["docutils-stubs", "flake8", "mypy"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-htmlhelp" +version = "2.0.4" +description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinxcontrib_htmlhelp-2.0.4-py3-none-any.whl", hash = "sha256:8001661c077a73c29beaf4a79968d0726103c5605e27db92b9ebed8bab1359e9"}, + {file = "sphinxcontrib_htmlhelp-2.0.4.tar.gz", hash = "sha256:6c26a118a05b76000738429b724a0568dbde5b72391a688577da08f11891092a"}, +] + +[package.dependencies] +Sphinx = ">=5" + +[package.extras] +lint = ["docutils-stubs", "flake8", "mypy"] +test = ["html5lib", "pytest"] + +[[package]] +name = "sphinxcontrib-jsmath" +version = "1.0.1" +description = "A sphinx extension which renders display math in HTML via JavaScript" +optional = false +python-versions = ">=3.5" +files = [ + {file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"}, + {file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"}, +] + +[package.extras] +test = ["flake8", "mypy", "pytest"] + +[[package]] +name = "sphinxcontrib-qthelp" +version = "1.0.6" +description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp documents" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinxcontrib_qthelp-1.0.6-py3-none-any.whl", hash = "sha256:bf76886ee7470b934e363da7a954ea2825650013d367728588732c7350f49ea4"}, + {file = "sphinxcontrib_qthelp-1.0.6.tar.gz", hash = "sha256:62b9d1a186ab7f5ee3356d906f648cacb7a6bdb94d201ee7adf26db55092982d"}, +] + +[package.dependencies] +Sphinx = ">=5" + +[package.extras] +lint = ["docutils-stubs", "flake8", "mypy"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-serializinghtml" +version = "1.1.9" +description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)" +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinxcontrib_serializinghtml-1.1.9-py3-none-any.whl", hash = "sha256:9b36e503703ff04f20e9675771df105e58aa029cfcbc23b8ed716019b7416ae1"}, + {file = "sphinxcontrib_serializinghtml-1.1.9.tar.gz", hash = "sha256:0c64ff898339e1fac29abd2bf5f11078f3ec413cfe9c046d3120d7ca65530b54"}, +] + +[package.dependencies] +Sphinx = ">=5" + +[package.extras] +lint = ["docutils-stubs", "flake8", "mypy"] +test = ["pytest"] + [[package]] name = "tomli" version = "2.0.1" @@ -384,6 +756,22 @@ files = [ {file = "typing_extensions-4.8.0.tar.gz", hash = "sha256:df8e4339e9cb77357558cbdbceca33c303714cf861d1eef15e1070055ae8b7ef"}, ] +[[package]] +name = "urllib3" +version = "2.1.0" +description = "HTTP library with thread-safe connection pooling, file post, and more." +optional = false +python-versions = ">=3.8" +files = [ + {file = "urllib3-2.1.0-py3-none-any.whl", hash = "sha256:55901e917a5896a349ff771be919f8bd99aff50b79fe58fec595eb37bbc56bb3"}, + {file = "urllib3-2.1.0.tar.gz", hash = "sha256:df7aa8afb0148fa78488e7899b2c59b5f4ffcfa82e6c54ccb9dd37c1d7b52d54"}, +] + +[package.extras] +brotli = ["brotli (>=1.0.9)", "brotlicffi (>=0.8.0)"] +socks = ["pysocks (>=1.5.6,!=1.5.7,<2.0)"] +zstd = ["zstandard (>=0.18.0)"] + [[package]] name = "zipp" version = "3.17.0" @@ -402,4 +790,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = ">=3.8" -content-hash = "3c9c9ed49319e674375823cd48bb1b9be4b5a26f8befd537b1b32f5213d868fc" +content-hash = "02f834911323a7b9bc641bab64832e9efd1a5cab6c14dc3152b3e35ae804b991" diff --git a/pyproject.toml b/pyproject.toml index d591669..84f39df 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,11 +7,13 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "chipshot" -version = "0.1.0" +version = "0.2.0" description = "Set up game-winning headers!" readme = "README.rst" authors = ["Kurt McKee "] license = "MIT" +repository = "https://github.com/kurtmckee/chipshot" +documentation = "https://chipshot.readthedocs.io" [tool.poetry.dependencies] python = ">=3.8" @@ -20,15 +22,18 @@ importlib_resources = { version = "*", python = "<3.9" } jinja2 = "*" tomli = { version = "*", python = "<3.11" } -[tool.poetry.group.testing.dependencies] +[tool.poetry.group.test.dependencies] coverage = { version = "*", extras = ["toml"] } pyfakefs = "*" pytest = "*" pytest-randomly = "*" -[tool.poetry.group.type-linting.dependencies] +[tool.poetry.group.mypy.dependencies] mypy = "*" +[tool.poetry.group.docs.dependencies] +sphinx = { version = "*", python = "3.12" } + [tool.poetry.scripts] chipshot = "chipshot.cli:run" @@ -37,8 +42,11 @@ chipshot = "chipshot.cli:run" # -------- [tool.chipshot] -template_root = "assets/headers" -template = "global.txt" +template = """ +This file is a part of Chipshot +Copyright 2022-{{ year }} Kurt McKee +SPDX-License-Identifier: MIT +""" # Coverage @@ -61,7 +69,7 @@ source = [ [tool.coverage.report] skip_covered = true -fail_under = 82 +fail_under = 76 # Mypy diff --git a/requirements/docs.txt b/requirements/docs.txt new file mode 100644 index 0000000..db63035 --- /dev/null +++ b/requirements/docs.txt @@ -0,0 +1,23 @@ +alabaster==0.7.13 ; python_version == "3.12" +babel==2.13.1 ; python_version == "3.12" +certifi==2023.11.17 ; python_version == "3.12" +charset-normalizer==3.3.2 ; python_version == "3.12" +colorama==0.4.6 ; python_version == "3.12" and sys_platform == "win32" +docutils==0.20.1 ; python_version == "3.12" +idna==3.6 ; python_version == "3.12" +imagesize==1.4.1 ; python_version == "3.12" +jinja2==3.1.2 ; python_version == "3.12" +markupsafe==2.1.3 ; python_version == "3.12" +packaging==23.2 ; python_version == "3.12" +pygments==2.17.2 ; python_version == "3.12" +requests==2.31.0 ; python_version == "3.12" +setuptools==69.0.2 ; python_version == "3.12" +snowballstemmer==2.2.0 ; python_version == "3.12" +sphinx==7.2.6 ; python_version == "3.12" +sphinxcontrib-applehelp==1.0.7 ; python_version == "3.12" +sphinxcontrib-devhelp==1.0.5 ; python_version == "3.12" +sphinxcontrib-htmlhelp==2.0.4 ; python_version == "3.12" +sphinxcontrib-jsmath==1.0.1 ; python_version == "3.12" +sphinxcontrib-qthelp==1.0.6 ; python_version == "3.12" +sphinxcontrib-serializinghtml==1.1.9 ; python_version == "3.12" +urllib3==2.1.0 ; python_version == "3.12" diff --git a/requirements/type-linting.txt b/requirements/mypy.txt similarity index 100% rename from requirements/type-linting.txt rename to requirements/mypy.txt diff --git a/requirements/testing.txt b/requirements/test.txt similarity index 100% rename from requirements/testing.txt rename to requirements/test.txt diff --git a/src/chipshot/cli.py b/src/chipshot/cli.py index 4158c85..3abefa3 100644 --- a/src/chipshot/cli.py +++ b/src/chipshot/cli.py @@ -10,12 +10,20 @@ import typing import click +import click.exceptions from . import compare, config, logger, reader, render, writer @click.command() @click.help_option("-h", "--help") +@click.version_option( + None, + "-V", + "--version", + prog_name="Chipshot", + message="%(prog)s v%(version)s", +) @click.option( "-c", "--config", @@ -24,32 +32,39 @@ """ The Chipshot configuration file to use. - If unspecified, 'pyproject.toml' in the current directory will be loaded. + If unspecified, '.chipshot.toml' in the current directory will be loaded. + If that doesn't exist, 'pyproject.toml' will be tried next. + Chipshot's default values will always be loaded first. """ ), type=click.Path(exists=True, file_okay=True, dir_okay=False), ) @click.option( - "--debug", + "--update", is_flag=True, - help="Enable logging of debug messages.", + help="Update files in-place.", ) @click.option( - "--update", + "-v", + "--verbose", is_flag=True, - help="Update files in-place.", + help="Enable verbose output.", ) @click.argument( "paths", nargs=-1, type=click.Path(exists=True, file_okay=True, dir_okay=True), ) -def run(config_file: str | None, update: bool, debug: bool, paths: tuple[str]) -> None: +def run( + config_file: str | None, update: bool, verbose: bool, paths: tuple[str] +) -> None: """Chipshot -- Set up game-winning headers!""" + files_updated = False + # Set up logging. - logger.setup(enable_debug=debug) + logger.setup(enable_debug=verbose) log = logging.getLogger(__name__) # Load the configuration. @@ -76,6 +91,7 @@ def run(config_file: str | None, update: bool, debug: bool, paths: tuple[str]) - # If this is a net-new header, log that information. if info.header and not info.original_header: log.info(f"{path}: Adding header (no original header found)") + files_updated = True # If there is an existing header, it might be kept or replaced. else: @@ -84,14 +100,19 @@ def run(config_file: str | None, update: bool, debug: bool, paths: tuple[str]) - # If the headers are sufficiently similar, replace the existing header. if similarity > 0.90: log.info(f"{path}: Updating header ({percentage} similarity)") + files_updated = True info.original_header = "" # The headers are sufficiently different. Keep the original header. else: log.info(f"{path}: Adding header ({percentage} similarity)") + files_updated = True if update: writer.write(info) + if files_updated: + raise click.exceptions.Exit(1) + def _get_files( paths: tuple[str], configuration: dict[str, typing.Any] diff --git a/src/chipshot/config.py b/src/chipshot/config.py index 9e934dd..da83e0c 100644 --- a/src/chipshot/config.py +++ b/src/chipshot/config.py @@ -28,25 +28,47 @@ def load(path: str | pathlib.Path | None = None) -> dict[str, t.Any]: """Load the default configuration and any specified config, if any.""" - config = _load_default_config() + # Try to load '.chipshot.toml' if no path was specified. + if path is None: + chipshot_toml = pathlib.Path(".chipshot.toml") + if chipshot_toml.is_file(): + log.debug("Defaulting to load a '.chipshot.toml' file") + path = chipshot_toml + + # If no path was specified and '.chipshot.toml' doesn't exist, + # try to load 'pyproject.toml'. if path is None: - # Try to load 'pyproject.toml'. pyproject_toml = pathlib.Path("pyproject.toml") if pyproject_toml.is_file(): - config.update(_load_toml(pyproject_toml)) - else: + log.debug("Defaulting to load a 'pyproject.toml' file") + path = pyproject_toml + + # If *path* is a string, convert it to a Path object. + if isinstance(path, str): path = pathlib.Path(path) - config.update(_load_toml(path)) + + custom_config = {} + if path is not None: + log.debug(f"Loading config file '{path}'") + custom_config = _load_toml(path) + + config = _load_default_config() + config.update(custom_config) return _normalize_config(config) def _load_toml(path: pathlib.Path) -> dict[str, t.Any]: - """Load configuration from a `pyproject.toml` file.""" + """Load configuration from a TOML file.""" toml = tomllib.loads(path.read_text("utf-8")) try: - config = toml["tool"]["chipshot"] + if path.name == "pyproject.toml": + log.debug("Looking for config in the 'tool.chipshot' key") + config = toml["tool"]["chipshot"] + else: # All other configuration files use a top-level "chipshot" key. + log.debug("Looking for config in the 'chipshot' key") + config = toml["chipshot"] if not isinstance(config, dict): raise exceptions.BadConfig(f"'tool.chipshot' in {path} is not a valid type") except KeyError: diff --git a/src/chipshot/exceptions.py b/src/chipshot/exceptions.py index ea837d4..e91592b 100644 --- a/src/chipshot/exceptions.py +++ b/src/chipshot/exceptions.py @@ -15,6 +15,10 @@ class ConfigNotFound(ChipshotError): """A config file was successfully loaded but no Chipshot configuration was found.""" +class NoTemplateDefined(ChipshotError): + """No *template* or *template_path* was found.""" + + class FileDecodeError(ChipshotError): """A file could not be decoded.""" diff --git a/src/chipshot/render.py b/src/chipshot/render.py index e8bb49e..c943511 100644 --- a/src/chipshot/render.py +++ b/src/chipshot/render.py @@ -10,6 +10,8 @@ import jinja2 +import chipshot.exceptions + def render_header(file: pathlib.Path, configuration: dict[str, t.Any]) -> str: """Render a (possibly file-specific) template into a header.""" @@ -21,21 +23,41 @@ def render_header(file: pathlib.Path, configuration: dict[str, t.Any]) -> str: suffix_config = configuration["extension"].get(suffix, {}) # Look for the correct template to load. - template_root = configuration.get("template_root", "") - template_path = ( - suffixes_config.get("template") - or suffix_config.get("template") - or configuration["template"] - ) - template = pathlib.Path(template_root) / template_path + jinja_loader: jinja2.DictLoader | jinja2.FileSystemLoader + # Check for a literal template or a template path for the file's suffixes config. + if "template" in suffixes_config: + template_name = "literal" + jinja_loader = jinja2.DictLoader({"literal": suffixes_config["template"]}) + elif "template_path" in suffixes_config: + template_path = pathlib.Path(suffixes_config["template_path"]) + template_name = template_path.name + jinja_loader = jinja2.FileSystemLoader(template_path.parent) + # Check for a literal template or a template path for the file's suffix config. + elif "template" in suffix_config: + template_name = "literal" + jinja_loader = jinja2.DictLoader({"literal": suffix_config["template"]}) + elif "template_path" in suffix_config: + template_path = pathlib.Path(suffix_config["template_path"]) + template_name = template_path.name + jinja_loader = jinja2.FileSystemLoader(template_path.parent) + # Check for a literal template or a template path in the global config. + elif "template" in configuration: + template_name = "literal" + jinja_loader = jinja2.DictLoader({"literal": configuration["template"]}) + elif "template_path" in configuration: + template_path = pathlib.Path(configuration["template_path"]) + template_name = template_path.name + jinja_loader = jinja2.FileSystemLoader(template_path.parent) + else: + raise chipshot.exceptions.NoTemplateDefined # Render the template. env = jinja2.Environment( - loader=jinja2.FileSystemLoader(template.parent), + loader=jinja_loader, undefined=jinja2.StrictUndefined, ) - template = env.get_template(template.name) - rendered_template: bytes = template.render( + template = env.get_template(template_name) + rendered_template: str = template.render( { "year": datetime.datetime.now().strftime("%Y"), }, diff --git a/tests/conftest.py b/tests/conftest.py index 187089b..35e2c3b 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -9,7 +9,8 @@ @pytest.fixture(scope="session") def _load_default_config_once(): - return chipshot.config.load() + defaults = chipshot.config._load_default_config() + return chipshot.config._normalize_config(defaults) @pytest.fixture diff --git a/tests/test_render.py b/tests/test_render.py index 888fc26..ac492de 100644 --- a/tests/test_render.py +++ b/tests/test_render.py @@ -14,12 +14,7 @@ @pytest.mark.parametrize("rendered_file", rendered_files) def test_render_header(default_config, rendered_file: pathlib.Path): - default_config.update( - { - "template_root": str(rendered_file.parent), - "template": "template.txt", - } - ) + default_config.update({"template_path": str(rendered_file.parent / "template.txt")}) expected = rendered_file.read_text() rendered = csr.render_header(rendered_file, default_config) fail_message = textwrap.dedent( diff --git a/tox.ini b/tox.ini index df37392..3710a61 100644 --- a/tox.ini +++ b/tox.ini @@ -3,13 +3,15 @@ envlist = coverage-erase py{3.12, 3.11, 3.10, 3.9, 3.8} coverage-report - type-linting + mypy + docs + isolated_build = True [testenv] depends = py{3.12, 3.11, 3.10, 3.9, 3.8}: coverage-erase -deps = -rrequirements/testing.txt +deps = -rrequirements/test.txt commands = coverage run -m pytest [testenv:coverage-erase] @@ -31,12 +33,19 @@ commands = commands_post = coverage html --fail-under=0 -[testenv:type-linting] -deps = -rrequirements/type-linting.txt +[testenv:mypy] +deps = -rrequirements/mypy.txt setenv = MYPY_FORCE_COLOR=1 commands = mypy +[testenv:docs] +base_python = py3.12 +skip_install = true +deps = -rrequirements/docs.txt +commands = + sphinx-build -aWEnqb html docs/ build/docs + [testenv:update] skip_install = true deps = @@ -46,8 +55,9 @@ deps = commands = # Update poetry.lock, and the testing dependencies. poetry update - poetry export --only=testing --without-hashes --output requirements/testing.txt - poetry export --only=type-linting --without-hashes --output requirements/type-linting.txt + poetry export --only=test --without-hashes --output requirements/test.txt + poetry export --only=mypy --without-hashes --output requirements/mypy.txt + poetry export --only=docs --without-hashes --output requirements/docs.txt # Update the pre-commit hooks and additional dependencies. pre-commit autoupdate