portly 0.1.0__tar.gz

portly-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: Bug report
+description: Report a problem with portly
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in as much
+        information as you can.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or commands that trigger the bug.
+      placeholder: |
+        ```python
+        import portly
+        portly.kill(8000)
+        ```
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: portly version
+      description: e.g. 0.1.0 (check `python -c "import portly; print(portly.__version__)"`)
+    validations:
+      required: true
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: e.g. 3.12, 3.14t (free-threaded)
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output / traceback
+      description: Paste any error messages or tracebacks.
+      render: shell

portly-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issues
+    url: https://github.com/PatrykBochenek/portly/security/policy
+    about: Please report security vulnerabilities privately — see SECURITY.md.
+  - name: Discussions
+    url: https://github.com/PatrykBochenek/portly/discussions
+    about: Ask questions, discuss ideas, and get help.

portly-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature request
+description: Suggest a new feature or improvement for portly
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an idea! Please describe the problem you're
+        solving and the shape of the solution you have in mind.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this feature solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How should the feature work? API sketches welcome.
+      placeholder: |
+        ```python
+        portly.wait_until_free(5432, interval=0.2)
+        ```
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds or alternative designs you've thought of.

portly-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+
+<!-- What does this PR do, and why? -->
+
+## Changes
+
+<!-- Bullet list of the concrete changes. -->
+
+## Testing
+
+<!-- How was this verified? e.g. "pytest tests/", "cargo test", "maturin build". -->
+
+## Checklist
+
+- [ ] `cargo fmt --check` and `cargo clippy -- -D warnings` pass
+- [ ] `ruff check` and `ruff format --check` pass
+- [ ] `mypy python/portly tests` passes
+- [ ] `pytest tests/` passes
+- [ ] Stub changes (`.pyi`) are validated by `mypy.stubtest`
+- [ ] CHANGELOG updated (if user-facing change)

portly-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev-dependencies:
+        patterns: ["maturin", "pytest", "pytest-cov", "ruff", "mypy"]

portly-0.1.0/.github/workflows/CI.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c  # stable
+        with:
+          components: rustfmt, clippy
+      - name: Install Python tooling
+        run: pip install ruff mypy maturin pytest
+      - name: Ruff check
+        run: ruff check python/ tests/ examples/
+      - name: Ruff format
+        run: ruff format --check python/ tests/ examples/
+      - name: Mypy (strict)
+        run: mypy python/portly tests
+      - name: Stubtest (stubs vs runtime)
+        run: |
+          maturin build --out dist
+          pip install dist/*.whl
+          python -m mypy.stubtest portly._lib --allowlist tests/stubtest-allowlist.txt
+      - name: Cargo fmt
+        run: cargo fmt -- --check
+      - name: Cargo clippy
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Cargo test
+        run: cargo test
+      - name: Zizmor (GitHub Actions security audit)
+        run: |
+          pip install zizmor
+          zizmor --min-severity high .github/workflows/
+
+  test:
+    name: Test (${{ matrix.os }} / ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c  # stable
+      - name: Install maturin
+        run: pip install maturin pytest
+      - name: Build extension
+        run: maturin build --out dist
+      - name: Install extension
+        shell: bash
+        run: pip install dist/*.whl
+      - name: Run tests
+        run: pytest tests/ -v
+
+  freethreaded:
+    name: Test (free-threaded 3.14t)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.14t"
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c  # stable
+      - name: Install maturin
+        run: pip install maturin pytest
+      - name: Build extension
+        run: maturin build --out dist
+      - name: Install extension
+        run: pip install dist/*.whl
+      - name: Run tests
+        run: pytest tests/ -v
+
+  wheel:
+    name: Wheel & sdist install test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c  # stable
+      - name: Install maturin
+        run: pip install maturin pytest
+      - name: Build and test wheel
+        run: |
+          maturin build --release --locked --out dist
+          pip install dist/*.whl
+          python -m pytest tests/ -q
+      - name: Build and test sdist
+        run: |
+          maturin sdist --out dist
+          pip install dist/*.tar.gz
+          python -m pytest tests/ -q

portly-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,34 @@
+name: Release Please
+
+# release-please opens a "chore(main): release vX.Y.Z" PR whenever conventional
+# commits land on main. Merging that PR bumps Cargo.toml/Cargo.lock and
+# CHANGELOG.md, then release-please creates the vX.Y.Z tag + GitHub Release.
+#
+# Because the tag is created with GITHUB_TOKEN, the tag-push event does NOT
+# trigger our release.yml (GitHub suppresses events caused by GITHUB_TOKEN).
+# Instead we dispatch release.yml on the tag via workflow_dispatch, which is
+# allowed for GITHUB_TOKEN.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@d1a8f221d7723166f48a584aebba00ef3f6febec  # v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          target-branch: main
+
+      - name: Trigger release build
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        run: gh workflow run release.yml --ref "${{ steps.release.outputs.tag_name }}"
+        env:
+          GH_TOKEN: ${{ github.token }}

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

@@ -0,0 +1,183 @@
+name: Release
+
+# Builds wheels + sdist for every supported platform and publishes them to
+# PyPI using Trusted Publishing (OIDC). Triggered by `v*` tags.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: aarch64
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.10"
+      - name: Build wheels
+        uses: PyO3/maturin-action@423a6347767a8b16e65c2a7a7042e4a921528da8  # v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --locked
+          sccache: false
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: aarch64
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.10"
+      - name: Build wheels
+        uses: PyO3/maturin-action@423a6347767a8b16e65c2a7a7042e4a921528da8  # v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --locked
+          sccache: false
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: windows-latest
+            target: x64
+            python_arch: x64
+          - runner: windows-11-arm
+            target: aarch64
+            python_arch: arm64
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+          architecture: ${{ matrix.platform.python_arch }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@423a6347767a8b16e65c2a7a7042e4a921528da8  # v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --locked
+          sccache: false
+      - name: Upload wheels
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      matrix:
+        platform:
+          - runner: macos-15-intel
+            target: x86_64
+          - runner: macos-latest
+            target: aarch64
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.10"
+      - name: Build wheels
+        uses: PyO3/maturin-action@423a6347767a8b16e65c2a7a7042e4a921528da8  # v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter --locked
+          sccache: false
+      - name: Upload wheels
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: Build sdist
+        uses: PyO3/maturin-action@423a6347767a8b16e65c2a7a7042e4a921528da8  # v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [linux, musllinux, windows, macos, sdist]
+    permissions:
+      # For artifact attestation and trusted publishing.
+      id-token: write
+      # For creating the GitHub Release.
+      contents: write
+      # For generating PEP 740 attestations.
+      attestations: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: Verify tag matches Cargo.toml version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          version="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match Cargo.toml version v${version}"
+            exit 1
+          fi
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      - name: Generate artifact attestation
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6  # v4
+        with:
+          subject-path: 'wheels-*/*'
+      - name: Create or update GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+            # release-please already created the release (with changelog notes);
+            # attach the wheels to it.
+            gh release upload "${GITHUB_REF_NAME}" wheels-*/* --clobber
+          else
+            gh release create "${GITHUB_REF_NAME}" wheels-*/* --generate-notes
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
+        with:
+          enable-cache: false
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/')
+        run: uv publish --trusted-publishing always 'wheels-*/*'

portly-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Rust
+/target
+**/*.rs.bk
+# Cargo.lock is committed intentionally (reproducible wheel/sdist builds).
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Maturin
+wheelhouse/

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

@@ -0,0 +1,36 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (strict)
+        entry: mypy python/portly tests
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt -- --check
+        language: system
+        pass_filenames: false
+      - id: cargo-clippy
+        name: cargo clippy
+        entry: cargo clippy --all-targets -- -D warnings
+        language: system
+        pass_filenames: false

portly-0.1.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.1.0"}

portly-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 (2026-08-16)
+
+
+### Features
+
+* rename python package and add typed stubs ([cfbcd68](https://github.com/PatrykBochenek/portly/commit/cfbcd68b18a2b7751837ed2d226caafb68cb2cda))
+
+
+### Bug Fixes
+
+* clippy flatten lint and Windows wheel install glob ([66c90dc](https://github.com/PatrykBochenek/portly/commit/66c90dce62e7259d935026cc26d4f9f1c1eb36a6))
+* clippy manual-flatten on the Linux socket table loops ([061c010](https://github.com/PatrykBochenek/portly/commit/061c010ca90f53c6d3efc8e21c8a40709ab3678f))
+* compile on Linux and Windows ([e300527](https://github.com/PatrykBochenek/portly/commit/e300527d5172146b0561a4bd47c127ee28c37d92))
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-16
+
+### Added
+
+- Initial release of **portly**: a cross-platform, Rust-powered library
+  for checking, finding, scanning, waiting on, and freeing TCP/UDP ports.
+- API: `is_available`, `find_free`, `wait_until_free`, `get_info`, `kill`,
+  `scan`, `__version__`.
+- Native (subprocess-free) process lookup on all platforms:
+  - Linux: `/proc/net/{tcp,tcp6,udp,udp6}` + `/proc/<pid>/fd` via `procfs`.
+  - macOS: `libproc` (`proc_pidinfo`).
+  - Windows: `GetExtended{Tcp,Udp}Table` + ToolHelp32 via `windows-sys`
+    (no dependency on the deprecated `wmic`).
+- Type stubs (`_lib.pyi`) validated by `mypy.stubtest`; `py.typed` marker.
+- CI: lint/typecheck gates, cross-platform test matrix (incl. free-threaded
+  3.14t), wheel + sdist install tests, and a release workflow using PyPI
+  Trusted Publishing with PEP 740 attestations.
+
+[Unreleased]: https://github.com/PatrykBochenek/portly/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/PatrykBochenek/portly/releases/tag/v0.1.0