onair 1.0.1__tar.gz

onair-1.0.1/.cursor/rules/global.mdc

@@ -0,0 +1,64 @@
+---
+description: Coding standards for every project generated from cookiecutter-python-seed
+alwaysApply: true
+---
+
+# Generated project standards
+
+This is a Python project generated from cookiecutter-python-seed. Treat `pyproject.toml` as the source of truth for toolchain, Python version, and dependencies. Minimum Python version is 3.12. Use uv to lock, sync, build, and bump versions.
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Before writing code
+
+Read the task and the code it touches, trace the real flow end to end, then stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse it.
+3. Does the standard library already do this? Use it.
+4. Does an already-declared dependency solve it? Use it.
+5. Can this be one boring line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Bug fix = root cause, not symptom. Grep every caller of the function you touch and fix the shared function once.
+
+## Toolchain
+
+- Match existing layout: `src/` for packages, `tests/` for tests, application entry points as already configured.
+- Do not add a dependency unless it is declared in `pyproject.toml` (or the project's lockfile). Prefer stdlib over a new package.
+- Style is enforced by Ruff. Follow `pyproject.toml`; the points below are the ones to apply consistently even when Ruff cannot.
+- After editing Python files, run `poe format`.
+- After editing Markdown files, run `poe format_docs`.
+
+## Comments and docs
+
+- No docstrings except on base/abstract classes and methods (the contract for implementors) and on complex functions where extra explanation genuinely helps.
+- No unnecessary comments. Code should be self-explanatory. If a comment is needed, explain why, not what.
+- No section-divider comments inside classes or functions. Group related methods by proximity. Dividers are allowed only in test classes.
+
+## Language
+
+- Type-hint every function and method. Do not nest annotations so deeply that they hurt readability.
+- No unnecessary imports.
+- Use f-strings for all string formatting.
+- Avoid unnecessary `Path` wrappers; join with `/` on `Path` objects.
+- ASCII only in identifiers, comments, and docs. No emojis. Non-ASCII letters are allowed only when the content is actually in another language (e.g. Polish, Russian).
+
+## Quality
+
+- Use `poe format` / `poe format_docs` instead of hand-formatting style.
+- Deletion over addition. Boring over clever. Fewest files possible. Shortest working diff wins, after you understand the problem.
+- No abstractions, boilerplate, or dependencies that weren't requested.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- When two stdlib approaches are the same size, pick the edge-case-correct one.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n^2) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+- Non-trivial logic leaves one runnable check: the smallest test that fails if the logic breaks. Trivial one-liners need no new test. Run the project's test command before claiming work is done.
+- Do not commit secrets, `.env` files, or local virtualenvs.
+
+Not lazy about: understanding the problem, input validation at trust boundaries, error handling that prevents data loss, security, anything explicitly requested.
+
+## Agents
+
+- Keep this file for conventions that should always apply.
+- Put path-specific Cursor rules in additional `.mdc` files in this directory.
+- Keep `AGENTS.md` as a short index that points here.

onair-1.0.1/.cursor/rules/markdown.mdc

@@ -0,0 +1,25 @@
+---
+description: Markdown formatting for README, docs, and other .md files
+globs: "**/*.md"
+alwaysApply: false
+---
+
+# Markdown
+
+ASCII only. No emojis, smart quotes, or non-English letters.
+
+Use fenced code blocks with a language tag when the snippet has a language:
+
+```python
+from pathlib import Path
+
+Path("data") / "out.csv"
+```
+
+Do not leave unlabeled fences for Python, TOML, shell, or JSON. Plain fences are fine for output or prose examples with no language.
+
+Keep heading levels, lists, and tables consistent within a file: one heading style, one list marker (`-`), one table alignment. Do not mix numbered and bulleted lists for the same kind of items.
+
+Skip extra bold, italics, and emphasis. Highlight a term only when it would otherwise be missed.
+
+Write short, plain sentences. If a technical term is necessary, introduce it in the same sentence.

onair-1.0.1/.github/workflows/check-tag.yml

@@ -0,0 +1,50 @@
+name: "Check Tag"
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Version tag like v1.2.3
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  check-tag:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-tags: true
+          fetch-depth: 0
+
+      - name: Check that tag is on main
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          git fetch origin refs/heads/main:refs/remotes/origin/main --force
+          if ! git merge-base --is-ancestor HEAD refs/remotes/origin/main; then
+            echo "tag $TAG is not on main"
+            exit 1
+          fi
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+          enable-cache: false
+
+      - name: Ensure tag matches version in pyproject.toml
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          version=$(uv version --short)
+          tag_version="${TAG#v}"
+          if [ "$version" != "$tag_version" ]; then
+            echo "version in pyproject.toml ($version) does not match tag ($TAG)"
+            exit 1
+          fi

onair-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: "Publish"
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  check-tag:
+    uses: ./.github/workflows/check-tag.yml
+    with:
+      tag: ${{ github.ref_name }}
+
+  build:
+    needs: check-tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+
+      - name: Build
+        run: uv build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/onair
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: false
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

onair-1.0.1/.github/workflows/quality-checks.yml

@@ -0,0 +1,40 @@
+name: "Quality Checks"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+
+      - name: Lock dependencies
+        run: uv lock --check
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Check code linting
+        run: uv run ruff check .
+
+      - name: Check Markdown formatting
+        run: find . -name '*.md' ! -path './.venv/*' ! -path './.git/*' -print0 | xargs -0 -r uv run mdformat --check
+
+      - name: Run tests
+        run: uv run pytest

onair-1.0.1/.github/workflows/version-check.yml

@@ -0,0 +1,61 @@
+name: "Version Check"
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    name: Ensure version bumped
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+          enable-cache: false
+
+      - name: Determine PR version
+        id: get-pr-version
+        run: echo "version=$(uv version --short)" >> "$GITHUB_OUTPUT"
+
+      - name: Determine main version
+        id: get-main-version
+        run: |
+          git fetch origin refs/heads/main:refs/remotes/origin/main --depth=1
+          git checkout -B main origin/main
+          main_version=$(uv version --short)
+          echo "Main version: $main_version"
+          echo "version=$main_version" >> "$GITHUB_OUTPUT"
+
+      - name: Compare versions
+        run: |
+          pr_version="${{ steps.get-pr-version.outputs.version }}"
+          main_version="${{ steps.get-main-version.outputs.version }}"
+
+          if [ -z "$pr_version" ] || [ -z "$main_version" ]; then
+            echo "Version is not set"
+            exit 1
+          fi
+
+          if [ "$pr_version" = "$main_version" ]; then
+            echo "Version unchanged ($pr_version). Please bump the version (e.g. poe patch)"
+            exit 1
+          fi
+
+          highest_version=$(echo -e "$pr_version\n$main_version" | sort -V | tail -n1)
+          if [ "$highest_version" != "$pr_version" ]; then
+            echo "Version $highest_version is higher than PR version $pr_version. Please bump the version (e.g. poe patch)"
+            exit 1
+          fi
+
+          echo "Version $pr_version is valid"

onair-1.0.1/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+
+__pycache__/
+*.py[cod]
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+.env
+.env.*
+
+.idea/
+.vscode/
+.DS_Store
+
+build/
+dist/
+sdist/
+wheels/
+*.egg-info/

onair-1.0.1/.mdformat.toml

@@ -0,0 +1,3 @@
+wrap = "keep"
+number = true
+end_of_line = "lf"

onair-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,63 @@
+minimum_pre_commit_version: '3.2.0'
+
+default_install_hook_types:
+  - pre-push
+  - post-checkout
+  - post-merge
+
+repos:
+  - repo: local
+    hooks:
+      - id: uv-lock-check
+        name: uv lock --check
+        description: check that uv.lock is consistent with pyproject.toml
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: '^(pyproject\.toml|uv\.lock)$'
+        stages: [pre-push]
+
+      - id: uv-lock-check-after-git
+        name: uv lock --check
+        description: check that uv.lock is consistent with pyproject.toml
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [post-checkout, post-merge]
+
+      - id: uv-sync
+        name: uv sync
+        description: sync dependencies
+
+        entry: uv sync --no-active --locked
+
+        language: system
+        always_run: true
+        pass_filenames: false
+        stages: [post-checkout, post-merge]
+        verbose: true
+
+      - id: ruff-check
+        name: ruff check
+        description: check for style issues
+        entry: uv run ruff check --force-exclude
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: ruff-format
+        name: ruff format
+        description: check that files are formatted
+        entry: uv run ruff format --check --force-exclude
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: md-format
+        name: md format
+        description: format markdown files
+        entry: uv run mdformat --check
+        language: system
+        files: '\.md$'
+        stages: [pre-push]

onair-1.0.1/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent instructions
+
+This project was generated from cookiecutter-python-seed.
+
+## Tooling
+
+- All AI IDEs: follow this file.
+- Cursor: project rules live in [`.cursor/rules/`](.cursor/rules/). This file is the index; do not duplicate those rules here.
+
+## Standards
+
+- Always-on: `.cursor/rules/global.mdc`
+- Markdown (`.md` files): `.cursor/rules/markdown.mdc`

onair-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+```shell
+uv sync
+```
+
+Commit `uv.lock`. `poe hooks` installs git hooks (pre-push, post-checkout, post-merge).
+
+```shell
+poe check
+poe check_docs
+poe test
+```
+
+`poe format` and `poe format_docs` apply the same tools in write mode.
+
+## Release
+
+Bump in the PR (`poe patch` / `minor` / `major`). CI fails if `[project].version` is not higher than on `main`.
+
+After merge, tag `vX.Y.Z` on `main` (must match the project version) and push the tag. GitHub Actions publishes the sdist and wheel to PyPI using trusted publishing. Register this repository as a trusted publisher on PyPI before the first release.

onair-1.0.1/LICENSE

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

onair-1.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: onair
+Version: 1.0.1
+Summary: Interactive internet radio for the terminal
+Project-URL: Homepage, https://github.com/roman-kaczanowski/onair
+Project-URL: Repository, https://github.com/roman-kaczanowski/onair
+Project-URL: Issues, https://github.com/roman-kaczanowski/onair/issues
+Author-email: Roman Kaczanowski <roman.kaczanowski.pl@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: prompt-toolkit
+Requires-Dist: python-vlc
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# onair
+
+[![CI](https://img.shields.io/github/actions/workflow/status/roman-kaczanowski/onair/quality-checks.yml?branch=main&style=flat-square&label=CI)](https://github.com/roman-kaczanowski/onair/actions/workflows/quality-checks.yml) [![PyPI](https://img.shields.io/pypi/v/onair?style=flat-square)](https://pypi.org/project/onair/) [![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://docs.python.org/3/) [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+
+Turn your terminal into an internet radio. onair is a small interactive shell for finding and playing stations by genre or country.
+
+## Features
+
+- Browse popular genres and countries.
+- Jump between stations and return to recently played ones.
+- Pause, resume, mute, and adjust volume without leaving the prompt.
+- Use tab completion, command history, and short aliases.
+- Discover stations through [Radio Browser](https://www.radio-browser.info/) without an API key.
+
+## Requirements
+
+- Python 3.12 or newer.
+- [VLC](https://www.videolan.org/vlc/) installed on your system. The `python-vlc` binding is installed with onair, but playback still requires the VLC application and its native library.
+
+## Quick start
+
+Install the release from PyPI:
+
+```shell
+python -m pip install onair
+onair
+```
+
+Or run it without installing by using [uv](https://docs.astral.sh/uv/):
+
+```shell
+uvx onair
+```
+
+To run the source:
+
+```shell
+uv sync
+uv run onair
+```
+
+Then choose a genre or country and start exploring:
+
+```text
+onair> help
+onair> play chillout
+onair> info
+onair> next
+onair> previous
+onair> country poland
+onair> volume +10
+onair> pause
+onair> resume
+onair> stop
+```
+
+Run `help` for every command and `help play` for command-specific examples. Running `play` without a genre resumes paused playback or chooses a genre at random.
+
+## Acknowledgments
+
+Inspired by cmd.fm. onair is an independent project and is not affiliated with or endorsed by cmd.fm.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and release process.
+
+## License
+
+Licensed under the [MIT License](LICENSE).

onair-1.0.1/README.md

@@ -0,0 +1,69 @@
+# onair
+
+[![CI](https://img.shields.io/github/actions/workflow/status/roman-kaczanowski/onair/quality-checks.yml?branch=main&style=flat-square&label=CI)](https://github.com/roman-kaczanowski/onair/actions/workflows/quality-checks.yml) [![PyPI](https://img.shields.io/pypi/v/onair?style=flat-square)](https://pypi.org/project/onair/) [![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://docs.python.org/3/) [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+
+Turn your terminal into an internet radio. onair is a small interactive shell for finding and playing stations by genre or country.
+
+## Features
+
+- Browse popular genres and countries.
+- Jump between stations and return to recently played ones.
+- Pause, resume, mute, and adjust volume without leaving the prompt.
+- Use tab completion, command history, and short aliases.
+- Discover stations through [Radio Browser](https://www.radio-browser.info/) without an API key.
+
+## Requirements
+
+- Python 3.12 or newer.
+- [VLC](https://www.videolan.org/vlc/) installed on your system. The `python-vlc` binding is installed with onair, but playback still requires the VLC application and its native library.
+
+## Quick start
+
+Install the release from PyPI:
+
+```shell
+python -m pip install onair
+onair
+```
+
+Or run it without installing by using [uv](https://docs.astral.sh/uv/):
+
+```shell
+uvx onair
+```
+
+To run the source:
+
+```shell
+uv sync
+uv run onair
+```
+
+Then choose a genre or country and start exploring:
+
+```text
+onair> help
+onair> play chillout
+onair> info
+onair> next
+onair> previous
+onair> country poland
+onair> volume +10
+onair> pause
+onair> resume
+onair> stop
+```
+
+Run `help` for every command and `help play` for command-specific examples. Running `play` without a genre resumes paused playback or chooses a genre at random.
+
+## Acknowledgments
+
+Inspired by cmd.fm. onair is an independent project and is not affiliated with or endorsed by cmd.fm.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and release process.
+
+## License
+
+Licensed under the [MIT License](LICENSE).