unref 0.0.1__tar.gz

unref-0.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What
+
+<!-- One or two lines: what this changes and why. Link the issue, e.g. "Refs #8". -->
+
+## Details
+
+<!--
+For a detection change, show a small Python example and the findings it now produces.
+Delete this section for pure refactors / docs / tooling.
+-->
+
+## Notes
+
+<!--
+Anything a reviewer needs: scope boundaries, known limitations, or explicit
+out-of-scope behavior. Delete if there's nothing to add.
+-->

unref-0.0.1/.github/actionlint.yaml

@@ -0,0 +1,7 @@
+# Path-specific configurations.
+paths:
+  # Composite actions are not supported.
+  # https://github.com/rhysd/actionlint/issues/401
+  .github/workflows/util/*/action.yml:
+    ignore:
+      - '.*'

unref-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+  workflow_dispatch:
+
+# A new push to a PR supersedes its in-flight run; manual runs are never cancelled.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  linters:
+    name: Linters
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Python
+        uses: ./.github/workflows/util/setup_python
+
+      - name: prek cache
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/prek
+          key: ci-prek-cache-${{ hashFiles('prek.toml') }}
+
+      - name: Run prek
+        run: prek run -v --show-diff-on-failure --color=always --all-files
+
+  type-check:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    name: Type Checks - Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./.github/workflows/util/setup_python
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run mypy
+        run: mypy --config-file linters/mypy.toml .
+
+      - name: Run ty
+        run: ty check --project . --config-file linters/ty.toml --python-version ${{ matrix.python-version }}
+
+  unit-tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    name: Unit Tests - Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./.github/workflows/util/setup_python
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        run: pytest --showlocals -c tests/pytest.ini
+
+  check:
+    name: Check All
+    if: always()
+    needs: [linters, type-check, unit-tests]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@v1.3.0
+        with:
+          jobs: ${{ toJSON(needs) }}

unref-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+  workflow_dispatch:
+
+jobs:
+  release:
+    # A manual run on a branch would build a dev version (.devN+g<hash>) that PyPI rejects,
+    # so only release from a version tag.
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC), so no API token is stored.
+      id-token: write
+      # Required to create the GitHub Release.
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs derives the version from the git tag, so it needs the
+          # full history and tags, not a shallow clone.
+          fetch-depth: 0
+
+      - uses: ./.github/workflows/util/setup_python
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true

unref-0.0.1/.github/workflows/util/setup_python/action.yml

@@ -0,0 +1,44 @@
+name: Setup Python
+description: Install Python, uv and dependencies.
+
+inputs:
+  python-version:
+    description: Python version to install.
+    default: "3.14"
+  resolution:
+    description: uv resolution strategy (e.g. lowest-direct). Empty installs the locked versions.
+    default: ""
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v10.3.2
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true
+
+    - name: Install Python dependencies
+      shell: bash
+      env:
+        RESOLUTION: ${{ inputs.resolution }}
+      run: |
+          if [ -n "$RESOLUTION" ]; then
+            uv sync --resolution "$RESOLUTION"
+          else
+            uv sync --frozen
+          fi
+
+    # Put the project virtual environment on PATH for subsequent steps, so tools can be
+    # invoked directly (e.g. `pytest`). Uses $GITHUB_PATH, which is applied
+    # regardless of the step's shell and works on all runners.
+    - name: Activate Python venv
+      shell: bash
+      run: |
+        if [ -d .venv/Scripts ]; then
+          # Windows layout ('.venv/Scripts'); '$(pwd -W)' yields a Windows-style path.
+          echo "$(pwd -W)/.venv/Scripts" >> "$GITHUB_PATH"
+        else
+          # Unix layout ('.venv/bin').
+          echo "$(pwd)/.venv/bin" >> "$GITHUB_PATH"
+        fi

unref-0.0.1/.gitignore

@@ -0,0 +1,18 @@
+# IDE
+.idea
+venv
+.venv
+.vscode
+.claude
+
+# Python
+__pycache__
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+dist
+
+# Temporary files
+tmp
+.cspellcache

unref-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to unref
+
+Thanks for your interest in contributing! To contribute, open a pull request with your changes, or an
+issue with your bug or request.
+
+All checks (linters, type checks, and tests) run automatically in CI through GitHub Actions.
+
+## Development environment
+
+Local development is done with [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+Install all the development dependencies:
+
+```shell
+uv sync
+```
+
+## Running checks locally
+
+Run the linters with `prek`:
+
+```shell
+uv run prek run -a
+```
+
+Run the unit tests with `pytest`:
+
+```shell
+uv run pytest -c tests/pytest.ini tests
+```
+
+Run the type checks with `mypy` and `ty` (both run in CI):
+
+```shell
+uv run mypy --config-file linters/mypy.toml .
+uv run ty check --project . --config-file linters/ty.toml
+```
+
+## Releasing
+
+To release a new version, run the interactive script (it requires the [`gh`](https://cli.github.com/) CLI,
+authenticated against the repository):
+
+```shell
+uv run scripts/release.py
+```

unref-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yossi Rozantsev
+
+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.

unref-0.0.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: unref
+Version: 0.0.1
+Summary: Find unreferenced Python code
+Project-URL: homepage, https://github.com/Apakottur/unref
+Project-URL: repository, https://github.com/Apakottur/unref
+Author: Yossi Rozantsev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dead-code,linter,static-analysis,unused-code
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+[![image](https://img.shields.io/pypi/v/unref.svg)](https://pypi.python.org/pypi/unref)
+[![image](https://img.shields.io/pypi/l/unref.svg)](https://github.com/Apakottur/unref/blob/main/LICENSE)
+[![image](https://img.shields.io/pypi/pyversions/unref.svg)](https://pypi.python.org/pypi/unref)
+
+# unref
+
+Find unreferenced Python code.
+
+`unref` reports the functions, classes and methods in a Python codebase that nothing references.
+
+> [!NOTE]
+> `unref` is in early development and does not do anything useful yet.
+
+## Why
+
+Finding dead code needs whole-program analysis: a function is unused only if no file in the project
+references it. [Ruff](https://docs.astral.sh/ruff/) analyses one file at a time and does not have this
+feature yet, see [astral-sh/ruff#872](https://github.com/astral-sh/ruff/issues/872).
+
+Use `unref` today, and migrate when Ruff ships it.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Apakottur/unref/blob/main/CONTRIBUTING.md).

unref-0.0.1/README.md

@@ -0,0 +1,24 @@
+[![image](https://img.shields.io/pypi/v/unref.svg)](https://pypi.python.org/pypi/unref)
+[![image](https://img.shields.io/pypi/l/unref.svg)](https://github.com/Apakottur/unref/blob/main/LICENSE)
+[![image](https://img.shields.io/pypi/pyversions/unref.svg)](https://pypi.python.org/pypi/unref)
+
+# unref
+
+Find unreferenced Python code.
+
+`unref` reports the functions, classes and methods in a Python codebase that nothing references.
+
+> [!NOTE]
+> `unref` is in early development and does not do anything useful yet.
+
+## Why
+
+Finding dead code needs whole-program analysis: a function is unused only if no file in the project
+references it. [Ruff](https://docs.astral.sh/ruff/) analyses one file at a time and does not have this
+feature yet, see [astral-sh/ruff#872](https://github.com/astral-sh/ruff/issues/872).
+
+Use `unref` today, and migrate when Ruff ships it.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Apakottur/unref/blob/main/CONTRIBUTING.md).

unref-0.0.1/linters/cspell/words.txt

@@ -0,0 +1,28 @@
+addopts
+anyio
+Apakottur
+commitish
+contextlib
+docstrings
+elif
+httpx
+ignorelist
+isort
+maxfail
+mypy
+pathlib
+prek
+pycache
+Pydocstyle
+pyproject
+pytest
+Rozantsev
+showlocals
+shpyx
+softprops
+subclassing
+taplo
+typeshed
+unref
+venv
+Yossi

unref-0.0.1/linters/cspell.json

@@ -0,0 +1,12 @@
+{
+  "dictionaries": [
+    "custom-words"
+  ],
+  "dictionaryDefinitions": [
+    {
+      "name": "custom-words",
+      "path": "./cspell/words.txt",
+      "addWords": true
+    }
+  ]
+}

unref-0.0.1/linters/mypy.toml

@@ -0,0 +1,105 @@
+# See: https://mypy.readthedocs.io/en/stable/config_file.html
+
+[tool.mypy]
+####################
+# Import discovery #
+####################
+# Suppresses error messages about imports that cannot be resolved.
+# This can be enabled per-module.
+ignore_missing_imports = false
+
+# See https://mypy.readthedocs.io/en/latest/running_mypy.html#following-imports
+follow_imports = "normal"
+follow_imports_for_stubs = true
+
+##########################
+# Platform configuration #
+##########################
+###########################
+# Disallow dynamic typing #
+###########################
+disallow_any_unimported = true
+disallow_any_expr = false
+disallow_any_decorated = false
+disallow_any_explicit = false
+disallow_any_generics = true
+disallow_subclassing_any = true
+#################################
+# Untyped definitions and calls #
+#################################
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+##############################
+# None and Optional handling #
+##############################
+implicit_optional = false
+strict_optional = true
+########################
+# Configuring warnings #
+########################
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_return_any = true
+warn_unreachable = true
+######################
+# Suppressing errors #
+######################
+ignore_errors = false
+##################################
+# Miscellaneous strictness flags #
+##################################
+allow_untyped_globals = false
+allow_redefinition = true
+local_partial_types = true
+# disable_error_code=
+# Optional error codes: https://mypy.readthedocs.io/en/stable/error_code_list2.html
+enable_error_code = [
+  "redundant-self",
+  "redundant-expr",
+  "possibly-undefined",
+  "truthy-bool",
+  "truthy-iterable",
+  "ignore-without-code",
+  "unused-awaitable",
+  # "explicit-override",
+  "mutable-override",
+  "exhaustive-match",
+]
+extra_checks = false
+implicit_reexport = false
+strict_equality = true
+strict_equality_for_none = true
+strict_bytes = true
+strict = true
+##############################
+# Configuring error messages #
+##############################
+show_error_context = false
+show_column_numbers = true
+show_error_code_links = false
+hide_error_codes = false
+# pretty=
+color_output = true
+error_summary = true
+show_absolute_path = false
+####################
+# Incremental mode #
+####################
+incremental = true
+####################
+# Advanced options #
+####################
+plugins = []
+warn_incomplete_stub = true
+#####################
+# Report generation #
+#####################
+#################
+# Miscellaneous #
+#################
+warn_unused_configs = true
+# verbosity=

unref-0.0.1/linters/ruff.toml

@@ -0,0 +1,130 @@
+########################
+# Global configuration #
+########################
+
+# Maximum line length.
+line-length = 120
+
+# Minimum supported Python version.
+target-version = "py311"
+
+# Enable autofixing.
+fix = true
+
+# Output format, can be used to print more detailed errors.
+output-format = "concise"
+
+[format]
+# Preview mode is unstable and should not be used.
+preview = false
+
+quote-style = "double"
+indent-style = "space"
+
+
+[lint]
+# Preview mode is unstable and should not be used.
+preview = false
+
+# Enable everything else.
+select = ["ALL"]
+fixable = ["ALL"]
+unfixable = []
+
+# Forcefully enable rules which are not enabled by 'ALL'.
+extend-select = [
+  # Disabled by the Google convention:
+  # https://docs.astral.sh/ruff/settings/#lint_pydocstyle_convention
+  "D213", # Multi-line docstring summary should start at the second line
+]
+
+# Ignore rules.
+ignore = [
+  ###########################################
+  # Ignored - Conflicts with Ruff formatter #
+  ###########################################
+  "COM812", # Trailing comma missing
+  "E501", # Line too long
+  "ISC001", # Implicitly concatenated strings on a single line
+  "ISC004", # Unparenthesized implicit string concatenation in collection
+  ##############
+  # Pydocstyle #
+  ##############
+  # See: http://www.pydocstyle.org/en/stable/error_codes.html
+  "D100", # Missing docstring in public module
+  "D101", # Missing docstring in public class
+  "D102", # Missing docstring in public method
+  "D103", # Missing docstring in public function
+  "D104", # Missing docstring in public package
+  "D105", # Missing docstring in magic method
+  "D106", # Missing docstring in public nested class
+  "D107", # Missing docstring in __init__
+  "D200", # One-line docstring should fit on one line with quotes
+  "D205", # 1 blank line required between summary line and description
+  "D212", # Multi-line docstring summary should start at the first line
+  "D415", # First line should end with a period, question mark, or exclamation point
+  ###################################
+  # Other checks that we don't want #
+  ###################################
+  "ANN401", # Dynamically typed expressions (typing.Any) are disallowed
+  "ASYNC109", # Async function definition with a `timeout` parameter
+  "ASYNC240", # Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+  "ASYNC250", # Blocking call to `input()` in async context
+  "BLE001", # Do not catch blind exception: `Exception`
+  "C901", # Method is too complex
+  "CPY001", # Missing copyright notice at top of file
+  "EM101", # Exception must not use a string literal, assign to variable first
+  "EM102", # Exception must not use an f-string literal, assign to variable first
+  "ERA001", # Found commented-out code
+  "FIX002", # Line contains TODO
+  "N818", # Exception name should be named with an Error suffix
+  "PLR0911", # Too many return statements
+  "PLR0912", # Too many branches
+  "PLR0913", # Too many arguments to function call
+  "PLR0915", # Too many statements
+  "PLR0917", # Too many positional arguments
+  "PLR1722", # Use `sys.exit()` instead of `exit`
+  "PLR2004", # Magic value used in comparison, consider replacing with a constant variable
+  "PLR5501", # Consider using `elif` instead of `else` then `if` to remove one indentation level
+  "PT003", # `scope='function'` is implied in `@pytest.fixture()`
+  "PTH123", # `open()` should be replaced by `Path.open()`
+  "RET505", # Unnecessary `else` after `return` statement
+  "RET506", # Unnecessary `else` after `raise` statement
+  "SIM102", # Use a single `if` statement instead of nested `if` statements
+  "SIM103", # Return the condition directly
+  "SIM105", # Use `contextlib.suppress()` instead of try-except-pass
+  "SIM108", # Use ternary operator `X` instead of `if`-`else`-block
+  "TC001", # Move application import into a type-checking block
+  "TC002", # Move third-party import into a type-checking block
+  "TC003", # Move standard library import into a type-checking block
+  "TD002", # Missing author in TODO
+  "TD003", # Missing issue link on the line following this TODO
+  "TRY003", # Avoid specifying long messages outside the exception class
+]
+
+[lint.isort]
+# Import sorting configuration.
+split-on-trailing-comma = false
+known-first-party = ["unref"]
+combine-as-imports = true
+
+[lint.pydocstyle]
+# Use Google-style docstrings.
+convention = "google"
+
+[lint.flake8-builtins]
+# Ignore list of builtin names.
+builtins-ignorelist = ["id"]
+
+[lint.flake8-tidy-imports]
+# Enforce absolute imports (TID252 only bans parent-relative by default).
+ban-relative-imports = "all"
+
+# Per file ignores.
+[lint.per-file-ignores]
+"tests/*" = [
+  "S101", # Use of `assert` detected
+]
+"scripts/*" = [
+  "T201", # `print` found
+]

unref-0.0.1/linters/taplo.toml

@@ -0,0 +1,2 @@
+[formatting]
+align_comments = false

unref-0.0.1/linters/ty.toml

@@ -0,0 +1,38 @@
+# See: https://docs.astral.sh/ty/reference/configuration
+
+
+[rules]
+# All rules are errors by default.
+all = "error"
+
+# Disable specific rules.
+unsupported-dynamic-base = "ignore"
+missing-override-decorator = "ignore"
+unsound-assignment = "ignore"
+unsound-return-statement = "ignore"
+unsound-yield = "ignore"
+
+[analysis]
+allowed-unresolved-imports = []
+replace-imports-with-any = []
+respect-type-ignore-comments = true
+
+[environment]
+extra-paths = []
+# python =
+# python-platform
+python-version = "3.14"
+# root = []
+# typeshed =
+
+# [[overrides]]
+
+[src]
+# exclude =
+# include =
+respect-ignore-files = true
+
+[terminal]
+error-on-warning = true
+# output-format = "full"
+output-format = "concise"

unref-0.0.1/linters/yamllint.yaml

@@ -0,0 +1,19 @@
+extends: default
+
+rules:
+  line-length:
+    max: 120
+
+  document-start:
+    present: false
+
+
+  comments:
+    require-starting-space: true
+    ignore-shebangs: true
+    min-spaces-from-content: 1
+
+
+  truthy:
+    allowed-values: ['true', 'false', 'on', 'off']
+    check-keys: true