usethis 0.1.0__tar.gz

usethis-0.1.0/.github/ISSUE_TEMPLATE/documentation-task.md

@@ -0,0 +1,23 @@
+---
+name: Documentation Task
+about: A tightly scoped task for adding or updating documentation.
+title: ''
+labels: ''
+assignees: nathanjmcdougall
+
+---
+
+**Motivation**
+A clear and concise description of what benefit you would get from this documentation update or addition.
+
+**Key Area**
+Specify the key area of the project that requires documentation, e.g. the function, the workflow, the developer experience, etc.
+
+**Objectives & Target Audience**
+Outline the objectives of the documentation task and describe the target audience. Specify the type of documentation (e.g., API documentation, user guide, tutorial) and what aspect you are specifically trying to communicate.
+
+**Steps**
+An outline of the steps required to create or update the documentation. Include details such as:
+
+- The specific content (e.g. text, code snippets, diagrams) to be added or updated.
+- The specific affected files

usethis-0.1.0/.github/ISSUE_TEMPLATE/feature-development-task.md

@@ -0,0 +1,29 @@
+---
+name: Feature Development Task
+about: A tightly scoped task for a developer.
+title: ''
+labels: ''
+assignees: nathanjmcdougall
+
+---
+
+**Motivation**
+A clear and concise description of what benefit you would get from this feature.
+
+**Summary of desired feature**
+A clear and concise description of what you want to happen.
+
+**Design**
+An explanation of the general approach and philosophy of the proposed design.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or feature, or designs you've considered.
+
+**Testing Strategy**
+What sort of tests will be written?
+
+**Steps**
+An outline of steps required to implement this feature.
+
+**Acceptance Criteria**
+When would enough be done to consider this task completed?

usethis-0.1.0/.github/ISSUE_TEMPLATE/feature-idea.md

@@ -0,0 +1,14 @@
+---
+name: Feature Idea
+about: A high-level description of a feature you'd like.
+title: ''
+labels: ''
+assignees: nathanjmcdougall
+
+---
+
+**Motivation**
+A clear and concise description of what benefit you would get from this feature.
+
+**Summary of desired feature**
+A clear and concise description of what you want to happen, at a high level.

usethis-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+on:
+  workflow_dispatch:
+  push:
+    branches: ['main']
+  pull_request:
+jobs:
+  tests:
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONIOENCODING: utf-8
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup git user config
+        run: |
+          git config --global user.name placeholder
+          git config --global user.email placeholder@example.com
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@3b9817b1bf26186f03ab8277bab9b827ea5cc254 # v3.2.0
+        with:
+          version: "latest"
+
+      - name: "Set up Python"
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+        
+      - name: Setup dependencies
+        run: |
+          uv export --resolution ${{ matrix.resolution }} > requirements.txt 
+          uv pip install --system --break-system-packages -r requirements.txt
+
+      - name: Run pre-commit
+        run: |
+          uv run --frozen pre-commit run --all-files
+
+      - name: Run pytest
+        uses: pavelzw/pytest-action@510c5e90c360a185039bea56ce8b3e7e51a16507 # v2.2.0
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.12, 3.13]
+        resolution: [highest, lowest-direct]

usethis-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+
+name: Release to PyPI
+on:
+  push:
+    tags:
+      - 'v*'
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+        - name: Checkout code
+          uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+        - name: Set up uv
+          uses: astral-sh/setup-uv@3b9817b1bf26186f03ab8277bab9b827ea5cc254 # v3.2.0
+          with:
+            version: "latest"
+
+        - name: "Set up Python"
+          uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+          with:
+            python-version: 3.12
+
+        - name: Release
+          run: |
+            uv build
+            uv publish --trusted-publishing always

usethis-0.1.0/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

usethis-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "v0.22"
+    hooks:
+      - id: validate-pyproject
+        additional_dependencies: ["validate-pyproject-schema-store[all]"]
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run --frozen ruff format
+        language: system
+        always_run: true
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff-check
+        entry: uv run --frozen ruff check --fix
+        language: system
+        always_run: true
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: deptry
+        name: deptry
+        entry: uv run --frozen deptry src
+        language: system
+        always_run: true
+        pass_filenames: false

usethis-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.4

usethis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nathan McDougall 
+
+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 without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usethis-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.3
+Name: usethis
+Version: 0.1.0
+Summary: Automate Python package and project setup tasks that are otherwise performed manually.
+Project-URL: Source Code, https://github.com/nathanjmcdougall/usethis-python
+Project-URL: Bug Tracker, https://github.com/nathanjmcdougall/usethis-python/issues
+Project-URL: source_archive, https://github.com/nathanjmcdougall/usethis-python/archive/f27d232986de7e36dbfed46afa106c0d839e7942.zip
+Author-email: Nathan McDougall <nathan.j.mcdougall@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Nathan McDougall 
+        
+        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 without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: init,project,setup,start,usethis
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: mergedeep>=1.3.4
+Requires-Dist: packaging>=24.1
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich>=13.8.1
+Requires-Dist: ruamel-yaml>=0.18.6
+Requires-Dist: tomlkit>=0.13.2
+Requires-Dist: typer>=0.12.5
+Description-Content-Type: text/markdown
+
+# usethis
+
+Automate Python package and project setup tasks that are otherwise performed manually.
+
+## Commands
+
+### `usethis tool`
+
+Add a new tool to a Python project, including:
+
+- declared & installed dependencies with `uv add`,
+- relevant `pyproject.toml` configuration,
+- any other relevant directories or tool-bespoke configuration files, and
+- `.pre-commit-config.yaml` configuration if using `pre-commit`.
+
+Currently supported tools:
+
+- ruff
+- pytest
+- deptry
+- pre-commit
+
+Example:
+
+`usethis tool ruff`
+
+Supported arguments:
+
+- `--remove` to remove the tool instead of adding it
+- `--offline` to disable network access and rely on caches
+
+### `usethis ci`
+
+Add Continuous Integration pipelines to the project.
+
+Currently supported platforms:
+
+- Bitbucket
+
+Example:
+
+`usethis ci bitbucket`.
+
+### `usethis browse pypi`
+
+Dispaly or open the PyPI landing page associated with another project.
+
+Example:
+
+`usethis browse pypi numpy`
+
+Supported arguments:
+
+- `--browser` to open the link in the browser automatically.
+
+## Development
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+### Hypothetical Interface
+
+The current interfaces are being considered:
+
+- `usethis tool` to configure a tool, e.g. `usethis tool ruff`. Adding a tool will install it, as well as add relevant files and/or configuration to use the tool. Tools can interact, for example if you run `usethis tool pytest` it will install `pytest`, add it as a testing dependency, etc. but if you then run `usethis tool ruff` then `usethis` will strategically configure `pytest` with `pytest`-specific linter rules. Also vice-versa - if you already have ruff configured but then run `usethis tool pytest`, then `usethis` will strategically add new ruff configuration to reflect the fact you are now using `pytest`. In this way, `usethis` calls are order-invariant.
+- `usethis badge` to add various badges. Note that you can often get the badge with `usethis tool ... --badge` when available for a tool.
+- `usethis browse` to browse something, e.g. `usethis browse pypi ruff` would open the URL to the PyPI page for `ruff` in the browser.
+- `usethis license` to choose a license, e.g. `usethis license mit` to use the MIT license.
+- `usethis file` to create a python file at the specifified location. Add the `--test` flag to create a corresponding test file in the `tests` directory.
+- `usethis package` to configure the packages distributed by your project.
+
+### Keeping Config Sections Synchronized
+
+Tools are not configured independently from one another. For example, if we are using pytest, we might want to enable the PTD rules in ruff, whereas if we are not using pytest, it really doesn't make sense to do this. Another example would be shared config, e.g. if two tools both need to know that the source code is in the `src` folder. One last example is a tool that cannot be used at all without another, e.g. `setuptools_scm` requires that we have setuptools in the first place.
+
+Each usethis function is potentially the dependent for another, and itself might have dependents. Both directions need to be considered when the function is designed and tested. In general, functions need to be able to read configuration to determine which actions to take, and then they need robust write functionality to extend existing config and append to existing files.
+
+Generally, information for tool configuration should be in `pyproject.toml` in the appropriate section. In rare cases, it might be necessary to store information in a `[tool.usethis]` section, although this is not yet clear.
+
+#### Worked Example
+
+We might run `usethis package` to make a distribution package associated with the project. This will be stored in the `packages` list in `[tool.setuptools]` in `pyproject.toml`. Then `usethis tool deptry` to set up deptry. This will add config to `pyproject.toml` for deptry, including ignoring the rule code DEP001 specifically for the packages listed by `usethis package`. If we added a new package with `usethis package --name other_package` then the deptry configuration would be extended to include this new package.

usethis-0.1.0/README.md

@@ -0,0 +1,81 @@
+# usethis
+
+Automate Python package and project setup tasks that are otherwise performed manually.
+
+## Commands
+
+### `usethis tool`
+
+Add a new tool to a Python project, including:
+
+- declared & installed dependencies with `uv add`,
+- relevant `pyproject.toml` configuration,
+- any other relevant directories or tool-bespoke configuration files, and
+- `.pre-commit-config.yaml` configuration if using `pre-commit`.
+
+Currently supported tools:
+
+- ruff
+- pytest
+- deptry
+- pre-commit
+
+Example:
+
+`usethis tool ruff`
+
+Supported arguments:
+
+- `--remove` to remove the tool instead of adding it
+- `--offline` to disable network access and rely on caches
+
+### `usethis ci`
+
+Add Continuous Integration pipelines to the project.
+
+Currently supported platforms:
+
+- Bitbucket
+
+Example:
+
+`usethis ci bitbucket`.
+
+### `usethis browse pypi`
+
+Dispaly or open the PyPI landing page associated with another project.
+
+Example:
+
+`usethis browse pypi numpy`
+
+Supported arguments:
+
+- `--browser` to open the link in the browser automatically.
+
+## Development
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+### Hypothetical Interface
+
+The current interfaces are being considered:
+
+- `usethis tool` to configure a tool, e.g. `usethis tool ruff`. Adding a tool will install it, as well as add relevant files and/or configuration to use the tool. Tools can interact, for example if you run `usethis tool pytest` it will install `pytest`, add it as a testing dependency, etc. but if you then run `usethis tool ruff` then `usethis` will strategically configure `pytest` with `pytest`-specific linter rules. Also vice-versa - if you already have ruff configured but then run `usethis tool pytest`, then `usethis` will strategically add new ruff configuration to reflect the fact you are now using `pytest`. In this way, `usethis` calls are order-invariant.
+- `usethis badge` to add various badges. Note that you can often get the badge with `usethis tool ... --badge` when available for a tool.
+- `usethis browse` to browse something, e.g. `usethis browse pypi ruff` would open the URL to the PyPI page for `ruff` in the browser.
+- `usethis license` to choose a license, e.g. `usethis license mit` to use the MIT license.
+- `usethis file` to create a python file at the specifified location. Add the `--test` flag to create a corresponding test file in the `tests` directory.
+- `usethis package` to configure the packages distributed by your project.
+
+### Keeping Config Sections Synchronized
+
+Tools are not configured independently from one another. For example, if we are using pytest, we might want to enable the PTD rules in ruff, whereas if we are not using pytest, it really doesn't make sense to do this. Another example would be shared config, e.g. if two tools both need to know that the source code is in the `src` folder. One last example is a tool that cannot be used at all without another, e.g. `setuptools_scm` requires that we have setuptools in the first place.
+
+Each usethis function is potentially the dependent for another, and itself might have dependents. Both directions need to be considered when the function is designed and tested. In general, functions need to be able to read configuration to determine which actions to take, and then they need robust write functionality to extend existing config and append to existing files.
+
+Generally, information for tool configuration should be in `pyproject.toml` in the appropriate section. In rare cases, it might be necessary to store information in a `[tool.usethis]` section, although this is not yet clear.
+
+#### Worked Example
+
+We might run `usethis package` to make a distribution package associated with the project. This will be stored in the `packages` list in `[tool.setuptools]` in `pyproject.toml`. Then `usethis tool deptry` to set up deptry. This will add config to `pyproject.toml` for deptry, including ignoring the rule code DEP001 specifically for the packages listed by `usethis package`. If we added a new package with `usethis package --name other_package` then the deptry configuration would be extended to include this new package.

usethis-0.1.0/doc/philosophy/introspection.md

@@ -0,0 +1,67 @@
+# Introspection when developing
+
+Nathan McDougall, August 2024.
+
+When developing, so many of our actions are reflexive. If you are interesting in
+developing usethis, then it is very valuable to slow down, and consider thoroughly
+which actions you are undertaking. Some of them might be running off-the-shelf automated
+tools. Sometimes you might be setting up bespoke configuration for those tools.
+Other times, you might have to do something manually.
+
+These are all useful points to note down and can provide a lot of insight into potential
+features for usethis (besides just being useful documentation).
+
+For example, when developing usethis, here are a list of actions that I undertook (not
+necessarily listed chronologically):
+
+## Toolset decisions
+
+- Use GitHub Actions for CI.
+- Always use the hash to pin the version of a GitHub action `uses:`
+- Use uv for package management.
+
+## Repo configuration
+
+- Created a repo on GitHub wih template .gitignore, MIT license and README.
+- Created a develop branch.
+- Set up sensible rulesets for branches.
+- Created a template for GitHub issues that are development tasks.
+- Ran `uv init --name usethis`.
+- Ran `uv python pin 3.12.4`.
+
+## Add GitHub Actions CI
+
+- Create a GitHub workflow file for CI manually in `.github/workflows/ci.yml`.
+- Use the following configuration to support GitFlow-style branch management:
+
+```yml
+name: CI
+on:
+    workflow_dispatch:
+    push:
+      branches: ['main', 'develop']
+    pull_request:
+```
+
+- Add <https://github.com/hynek/setup-cached-uv>.
+- Add <https://github.com/actions/checkout>.
+- Set up the GitHub actions matrix to use Ubuntu, Windows and MacOS.
+- Set up the GitHub actions to use different Python versions.
+- Set up logic to use uv in GitHub actions.
+
+## Local development configuration
+
+- Cloned the repo from GitHub.
+- Ran `uv sync`.
+- Set up git username, email, and signing key.
+
+## Set up tests
+
+- Ran `uv add --dev pytest`.
+- Created a tests folder.
+- Added a trivial test module `test_nothing.py`.
+- Add a trivial test `test_pass` to the test module.
+- Add pytest, pytest-md and pytest-emoji as dev deependencies.
+- Confirm pytest is working with `pytest tests` in the CLI.
+- Add <https://github.com/pavelzw/pytest-action> to set up pytest in CI, using the
+  correct CLI args to pytest.