orphans 1.0.0__tar.gz

orphans-1.0.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,49 @@
+name: Bug report
+description: Something orphans does is wrong or broken
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Fill in what you can.
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 14, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: orphans version
+      placeholder: "run orphans --version and paste the output"
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command you ran
+      placeholder: "orphans --cleanup --dry-run"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected to happen
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happened
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: managers
+    attributes:
+      label: Package managers you have installed
+      placeholder: "pip, npm, cargo, brew"
+    validations:
+      required: false

orphans-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://github.com/ado11231/orphans#readme
+    about: Read the README for install steps and usage.
+  - name: PyPI page
+    url: https://pypi.org/project/orphans/
+    about: The published package on PyPI.

orphans-1.0.0/.github/ISSUE_TEMPLATE/install.yml

@@ -0,0 +1,44 @@
+name: Installation help
+description: orphans will not install or will not run after install
+labels: ["install"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Tell us what went wrong during install. The more detail you give, the
+        faster we can help.
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 14, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.4"
+    validations:
+      required: true
+  - type: input
+    id: how
+    attributes:
+      label: How did you install orphans
+      placeholder: "pipx install orphans, pip install ., from the wheel"
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command you ran
+      placeholder: "orphans --version"
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Full error output
+      render: shell
+    validations:
+      required: true

orphans-1.0.0/.github/ISSUE_TEMPLATE/manager.yml

@@ -0,0 +1,30 @@
+name: Package manager request
+description: Ask about a package manager orphans does not scan yet
+labels: ["manager"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        orphans scans pip, npm, cargo, and Homebrew today. If you want another
+        package manager added, tell us which one and why.
+  - type: input
+    id: manager
+    attributes:
+      label: Package manager name
+      placeholder: "yarn, pnpm, apt, dnf"
+    validations:
+      required: true
+  - type: input
+    id: link
+    attributes:
+      label: Link to its website or docs
+      placeholder: "https://yarnpkg.com"
+    validations:
+      required: false
+  - type: textarea
+    id: why
+    attributes:
+      label: Why you want it added
+      placeholder: "I use it every day and I have no way to find orphans in it."
+    validations:
+      required: true

orphans-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install ruff pytest
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: python -m pytest tests/ -q
+
+  build-and-install:
+    # Build the wheel exactly as release.yml does and install it in a clean
+    # pipx environment, so a packaging regression (missing module, broken
+    # console-script, version metadata) is caught before tag + publish.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build + install tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade build pipx
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: pipx-install the built wheel
+        run: pipx install --force dist/*.whl
+
+      - name: console-script runs and --version works
+        run: orphans --version

orphans-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release (PyPI)
+
+# Builds the wheel + sdist on a pushed v* tag and publishes to PyPI using
+# OIDC trusted publishing (no stored API token). Configure the trusted
+# publisher once on pypi.org first — see docs/RELEASE.md.
+on:
+  push:
+    tags:
+      - "v*"
+
+# OIDC trusted publishing requires id-token: write.
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tooling
+        run: pip install --upgrade build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Smoke-install the wheel and run --version
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl
+          orphans --version
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

orphans-1.0.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.benchmarks/
+
+*.db
+*.sqlite
+*.sqlite3
+
+.env
+.env.local
+
+.DS_Store
+Thumbs.db
+
+.vscode/
+.idea/

orphans-1.0.0/LICENSE

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

orphans-1.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: orphans
+Version: 1.0.0
+Summary: See every package installed on your machine and know which ones are safe to remove.
+Project-URL: Homepage, https://github.com/ado11231/orphans
+Project-URL: Repository, https://github.com/ado11231/orphans
+Project-URL: Issues, https://github.com/ado11231/orphans/issues
+Author: Adnan Alagic
+License: MIT License
+        
+        Copyright (c) 2026 adnan
+        
+        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: auditor,cargo,cleanup,homebrew,npm,orphan,package-manager,pip
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: packaging>=20.0
+Requires-Dist: pipdeptree<3.0,>=2.0
+Requires-Dist: rich<14.0,>=13.0
+Description-Content-Type: text/markdown
+
+<h3 align="center">orphans</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/orphans/"><img src="docs/badges/pypi.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="docs/badges/python.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="docs/demo.png" alt="orphans screenshot" width="600">
+</p>
+
+<p align="center"><b>See every package on your machine and know which ones you can remove.</b></p>
+
+<p align="center">
+  <b>orphans</b> looks at every package installed on your computer. It tells you
+  which ones are safe to remove. It never removes anything without asking you first.
+</p>
+
+<h3 align="center">Supported Package Managers</h3>
+
+<p align="center">
+  <a href="https://pip.pypa.io"><img src="docs/badges/pip.svg" alt="pip"></a>
+  <a href="https://www.npmjs.com"><img src="docs/badges/npm.svg" alt="npm"></a>
+  <a href="https://doc.rust-lang.org/cargo"><img src="docs/badges/cargo.svg" alt="cargo"></a>
+  <a href="https://brew.sh"><img src="docs/badges/homebrew.svg" alt="Homebrew"></a>
+</p>
+
+## Installation
+
+Python 3.11 or newer required. Install orphans with pipx.
+
+```bash
+pipx install orphans
+```
+
+Can be installed from source code.
+
+```bash
+git clone https://github.com/ado11231/orphans
+cd orphans
+pip install .
+```
+
+Check Installation.
+
+```bash
+orphans --version
+```
+
+## Usage
+
+Run orphans to scan your machine.
+
+```bash
+orphans
+```
+
+
+| Flag | What it does |
+| --- | --- |
+| `orphans --cleanup` | Removes orphan packages |
+| `orphans --cleanup --dry-run` | Shows what would be removed |
+| `orphans --repair` | Updates old packages |
+| `orphans --export results.json` | Saves results to a file |
+| `orphans --format json` | Prints results as json |
+| `orphans --snapshot` | Saves the current state |
+| `orphans --rollback <snapshot>` | Restores a saved state |
+| `orphans --watch` | Scans again every minute |
+| `orphans --version` | Shows the version |
+
+## License
+
+MIT, see [LICENSE](LICENSE).

orphans-1.0.0/README.md

@@ -0,0 +1,74 @@
+<h3 align="center">orphans</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/orphans/"><img src="docs/badges/pypi.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="docs/badges/python.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="docs/demo.png" alt="orphans screenshot" width="600">
+</p>
+
+<p align="center"><b>See every package on your machine and know which ones you can remove.</b></p>
+
+<p align="center">
+  <b>orphans</b> looks at every package installed on your computer. It tells you
+  which ones are safe to remove. It never removes anything without asking you first.
+</p>
+
+<h3 align="center">Supported Package Managers</h3>
+
+<p align="center">
+  <a href="https://pip.pypa.io"><img src="docs/badges/pip.svg" alt="pip"></a>
+  <a href="https://www.npmjs.com"><img src="docs/badges/npm.svg" alt="npm"></a>
+  <a href="https://doc.rust-lang.org/cargo"><img src="docs/badges/cargo.svg" alt="cargo"></a>
+  <a href="https://brew.sh"><img src="docs/badges/homebrew.svg" alt="Homebrew"></a>
+</p>
+
+## Installation
+
+Python 3.11 or newer required. Install orphans with pipx.
+
+```bash
+pipx install orphans
+```
+
+Can be installed from source code.
+
+```bash
+git clone https://github.com/ado11231/orphans
+cd orphans
+pip install .
+```
+
+Check Installation.
+
+```bash
+orphans --version
+```
+
+## Usage
+
+Run orphans to scan your machine.
+
+```bash
+orphans
+```
+
+
+| Flag | What it does |
+| --- | --- |
+| `orphans --cleanup` | Removes orphan packages |
+| `orphans --cleanup --dry-run` | Shows what would be removed |
+| `orphans --repair` | Updates old packages |
+| `orphans --export results.json` | Saves results to a file |
+| `orphans --format json` | Prints results as json |
+| `orphans --snapshot` | Saves the current state |
+| `orphans --rollback <snapshot>` | Restores a saved state |
+| `orphans --watch` | Scans again every minute |
+| `orphans --version` | Shows the version |
+
+## License
+
+MIT, see [LICENSE](LICENSE).

orphans-1.0.0/core/aliases.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+KNOWN_ALIASES: list[tuple[str, str]] = [
+    ("Pillow", "pil"),
+    ("PyYAML", "yaml"),
+    ("python-dateutil", "dateutil"),
+    ("python-dotenv", "dotenv"),
+    ("markdown-it-py", "markdown_it"),
+    ("paho-mqtt", "paho"),
+    ("influxdb-client", "influxdb_client"),
+    ("Pygments", "pygments"),
+    ("pyserial", "serial"),
+    ("cffi", "cffi"),
+    ("cryptography", "cryptography"),
+    ("certifi", "certifi"),
+    ("six", "six"),
+    ("rich", "rich"),
+    ("click", "click"),
+    ("fastapi", "fastapi"),
+    ("uvicorn", "uvicorn"),
+    ("numpy", "numpy"),
+    ("pydantic", "pydantic"),
+    ("starlette", "starlette"),
+    ("httptools", "httptools"),
+    ("uvloop", "uvloop"),
+    ("websockets", "websockets"),
+    ("watchfiles", "watchfiles"),
+    ("python-multipart", "python_multipart"),
+    ("aenum", "aenum"),
+    ("reactivex", "reactivex"),
+    ("reedsolo", "reedsolo"),
+    ("typing-extensions", "typing_extensions"),
+    ("typing-inspection", "typing_inspection"),
+    ("pydantic-core", "pydantic_core"),
+    ("annotated-types", "annotated_types"),
+    ("rich-click", "rich_click"),
+    ("esp-idf-nvs-partition-gen", "esp_idf_nvs_partition_gen"),
+    ("intelhex", "intelhex"),
+    ("bitstring", "bitstring"),
+    ("bitarray", "bitarray"),
+    ("esptool", "esptool"),
+    ("tibs", "tibs"),
+]
+
+PACKAGE_TO_IMPORT: dict[str, str] = {
+    p.lower().replace("-", "_"): i for p, i in KNOWN_ALIASES
+}
+
+IMPORT_TO_PACKAGE: dict[str, str] = {
+    i: p for p, i in KNOWN_ALIASES
+}

orphans-1.0.0/core/analyzer.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from models.package import InstallType, Package
+
+
+def find_orphans(packages: list[Package]) -> list[Package]:
+    return [
+        pkg for pkg in packages
+        if pkg.install_type == InstallType.DEPENDENCY
+        and not pkg.dependents
+    ]