unicode-animatio 0.0.1__tar.gz

unicode_animatio-0.0.1/.github/release.yml

@@ -0,0 +1,37 @@
+changelog:
+  exclude:
+    labels:
+      - skip-release-notes
+    authors:
+      - github-actions
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking-change
+        - semver-major
+    - title: Features
+      labels:
+        - feature
+        - enhancement
+        - semver-minor
+    - title: Fixes
+      labels:
+        - fix
+        - bug
+        - bugfix
+    - title: Docs
+      labels:
+        - docs
+        - documentation
+    - title: Maintenance
+      labels:
+        - chore
+        - refactor
+        - build
+        - ci
+        - test
+        - dependencies
+        - release
+    - title: Other Changes
+      labels:
+        - "*"

unicode_animatio-0.0.1/.github/workflows/quality.yml

@@ -0,0 +1,121 @@
+name: Quality
+
+on:
+  pull_request:
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dev environment
+        run: make dev-install
+
+      - name: Validate pre-commit config
+        run: ./.venv/bin/python3.11 -m pre_commit validate-config
+
+      - name: Run pre-commit on changed files
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            git fetch --no-tags origin "${GITHUB_BASE_REF}"
+            base_commit="$(git merge-base HEAD FETCH_HEAD)"
+            ./.venv/bin/python3.11 -m pre_commit run \
+              --from-ref "${base_commit}" \
+              --to-ref HEAD \
+              --show-diff-on-failure
+            exit 0
+          fi
+          if [[ -n "${BEFORE_SHA}" && "${BEFORE_SHA}" != "0000000000000000000000000000000000000000" ]]; then
+            ./.venv/bin/python3.11 -m pre_commit run \
+              --from-ref "${BEFORE_SHA}" \
+              --to-ref HEAD \
+              --show-diff-on-failure
+            exit 0
+          fi
+          files=(
+            .pre-commit-config.yaml
+            .github/release.yml
+            .github/workflows/release.yml
+            .github/workflows/quality.yml
+            CONTRIBUTING.md
+            docs/getting-started.md
+            Makefile
+            README.md
+            pyproject.toml
+            scripts/validate_commit_message.py
+          )
+          ./.venv/bin/python3.11 -m pre_commit run \
+            --files "${files[@]}" \
+            --show-diff-on-failure
+
+      - name: Validate pushed commit messages
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          set -euo pipefail
+          commits=()
+          if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            if [[ "${GITHUB_HEAD_REF}" == "dev" && "${GITHUB_BASE_REF}" == "main" ]]; then
+              # Long-lived dev pushes already validate each new commit on push.
+              # Re-validating the full dev ancestry here would fail on older
+              # branch history that predates the current commit policy.
+              commits=(HEAD)
+            else
+              git fetch --no-tags --depth=1 origin "${GITHUB_BASE_REF}"
+              base_commit="$(git merge-base HEAD FETCH_HEAD)"
+              mapfile -t commits < <(git rev-list --reverse "${base_commit}..HEAD")
+            fi
+          elif [[ -n "${BEFORE_SHA}" && "${BEFORE_SHA}" != "0000000000000000000000000000000000000000" ]]; then
+            mapfile -t commits < <(git rev-list --reverse "${BEFORE_SHA}..HEAD")
+          fi
+          if [[ ${#commits[@]} -eq 0 ]]; then
+            commits=(HEAD)
+          fi
+          for commit in "${commits[@]}"; do
+            subject="$(git log -1 --format=%s "${commit}")"
+            echo "Checking ${commit}: ${subject}"
+            ./.venv/bin/python3.11 scripts/validate_commit_message.py --subject "${subject}"
+          done
+
+      - name: Run package check
+        run: make check
+
+      - name: Run release smoke
+        run: make release-check
+
+  compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install compatibility test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run compatibility tests
+        run: pytest -q

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

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index target"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.target || (contains(github.ref_name, 'rc') && 'testpypi' || 'pypi') }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dev environment
+        run: make dev-install
+
+      - name: Run hooks
+        run: make hooks-run
+
+      - name: Run package check
+        run: make check
+
+      - name: Run release check
+        run: make release-check
+
+      - name: Upload built distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: unicode-animatio-dist
+          path: dist/*
+
+      - name: Publish to TestPyPI
+        if: ${{ (github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi') || (github.event_name == 'push' && contains(github.ref_name, 'rc')) }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to PyPI
+        if: ${{ (github.event_name == 'push' && !contains(github.ref_name, 'rc')) || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi') }}
+        uses: pypa/gh-action-pypi-publish@release/v1

unicode_animatio-0.0.1/.gitignore

@@ -0,0 +1,33 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checker / linter caches
+.mypy_cache/
+.ruff_cache/
+
+# IDE / OS
+.DS_Store
+.vscode/
+.idea/
+
+# Sweep and review artifacts
+workspace-tmp/

unicode_animatio-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+default_install_hook_types: [pre-commit, commit-msg]
+
+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
+        args: [--allow-multiple-documents]
+      - id: check-toml
+      - id: check-merge-conflict
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.10
+    hooks:
+      - id: actionlint
+
+  - repo: local
+    hooks:
+      - id: commit-message-policy
+        name: commit message policy
+        entry: ./.venv/bin/python3.11 scripts/validate_commit_message.py
+        language: system
+        stages: [commit-msg]
+      - id: ruff-check
+        name: ruff check --fix
+        entry: ./.venv/bin/python3.11 -m ruff check --fix
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: ./.venv/bin/python3.11 -m ruff format
+        language: system
+        types_or: [python, pyi]

unicode_animatio-0.0.1/API_COMPATIBILITY.md

@@ -0,0 +1,54 @@
+# unicode-animatio API Compatibility
+
+Status: `beta`
+Scope: public import roots and compatibility expectations for
+`unicode-animatio`
+
+Public naming note: the public distribution and CLI names use
+`unicode-animatio`, while the Python import roots remain `unicode_animations`.
+
+## Stable import roots
+
+The current public import roots are:
+
+- `unicode_animations`
+- `unicode_animations.cli`
+- `unicode_animations.web`
+
+## Stable public names
+
+The package currently treats these names as public:
+
+- `Spinner`
+- `BrailleSpinnerName`
+- `BRAILLE_SPINNER_NAMES`
+- `spinners`
+- `make_grid`
+- `grid_to_braille`
+- `makeGrid`
+- `gridToBraille`
+
+## CLI contract
+
+The package currently treats these console scripts as public:
+
+- `unicode-animatio`
+- `unicode-animatio-web`
+
+## Compatibility policy
+
+For the current beta surface:
+
+- new public names may be added in minor releases
+- existing public names should not be renamed or removed without a documented
+  compatibility note
+- JS-style aliases remain part of the compatibility surface until this file
+  says otherwise
+
+## Non-contract internals
+
+The package does not currently promise compatibility for:
+
+- private helper functions prefixed with `_`
+- the exact HTML/CSS markup of the local browser demo
+- internal frame-generation helper structure in `braille.py`

unicode_animatio-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,120 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Taking responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and also applies when
+an individual is officially representing the project in public spaces.
+Examples of representing our project include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening a private report to project maintainers through the
+repository's communication channels. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Project maintainers will follow these Community Impact Guidelines in
+determining consequences for any action they deem in violation of this Code of
+Conduct:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning from maintainers, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series of
+actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact:** A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact:** Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+https://github.com/mozilla/diversity.
+
+[homepage]: https://www.contributor-covenant.org

unicode_animatio-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,147 @@
+# Contributing to unicode-animatio
+
+Thanks for your interest in improving `unicode-animatio`.
+
+## Read first
+
+1. [README.md](./README.md)
+2. [API_COMPATIBILITY.md](./API_COMPATIBILITY.md)
+3. [docs/README.md](./docs/README.md)
+4. [docs/getting-started.md](./docs/getting-started.md)
+5. [docs/source-tree-owner-map.md](./docs/source-tree-owner-map.md)
+6. [RELEASING.md](./RELEASING.md) when the work affects packaging or release
+   behavior
+
+Treat the package README and API compatibility policy as the stable public
+contract. `unicode-animatio` ships deterministic frame data, CLI helpers, and
+simple browser preview support. It should stay lightweight and dependency-aware.
+
+## Development setup
+
+Requires Python 3.11+ for the shared local quality loop.
+
+```bash
+# 1. Clone and enter the repo
+git clone https://github.com/openminion/unicode-animatio.git unicode-animatio
+cd unicode-animatio
+
+# 2. Create and activate a virtualenv
+python3.11 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install in editable mode with dev extras
+make dev-install
+
+# 4. Install local hooks, including commit-message enforcement
+make hooks-install
+```
+
+## Running tests
+
+```bash
+# Full package test suite
+make test
+
+# Full local quality gate
+make check
+
+# Release/install smoke
+make release-check
+```
+
+If you need a narrower loop while iterating, run `python3.11 -m pytest -q
+tests/<target>` inside the activated virtualenv.
+
+## Running lint and formatting
+
+```bash
+# Lint only
+make lint
+
+# Check formatting without rewriting files
+make format-check
+
+# Apply formatting and autofixes
+make fix
+```
+
+If pre-commit, `make hooks-run`, or GitHub Actions reports formatter changes,
+run `make fix`, review the diff, rerun `make check`, and recommit before
+pushing again.
+
+## Running the demos
+
+Terminal demo (Python API):
+
+```bash
+python examples/terminal_demo.py
+```
+
+CLI demo:
+
+```bash
+unicode-animatio --list
+unicode-animatio helix
+unicode-animatio --web
+```
+
+## Development basics
+
+1. Keep pull requests focused and small when possible.
+2. Include tests for behavior changes.
+3. Keep frame definitions deterministic and easy to inspect.
+4. Avoid growing the package into a stateful runtime or unrelated UI framework.
+5. Keep docs and examples copy/paste friendly.
+
+Commit message guidance:
+
+1. Use commit messages in the form `<type>: <summary>` or
+   `<type>(<scope>): <summary>`.
+2. Approved current types are `feat`, `fix`, `docs`, `refactor`, `test`,
+   `chore`, `style`, and `build`.
+3. In this package, scope is optional but encouraged when it improves owner
+   clarity, for example `cli`, `web`, `braille`, `docs`, or `release`.
+4. Keep the summary specific to the landed change and avoid vague messages like
+   `update`.
+5. Prefer the most specific truthful type; do not use `chore` when `docs`,
+   `test`, `refactor`, or `build` is more accurate.
+6. Do not use local shorthand or planning labels as normal commit types.
+
+The same policy runs locally through `make hooks-install` and again in GitHub
+Actions on pull requests plus `dev`/`main` pushes.
+
+Preferred PR shape:
+
+`Improve browser preview packaging checks`
+
+- add ...
+- align ...
+- document ...
+
+Validation
+- `<command>`
+- `<command>`
+
+## Pull requests
+
+1. Be respectful and collaborative. Please follow the
+   [Code of Conduct](CODE_OF_CONDUCT.md).
+2. Make your change; add or update tests; run the relevant local validation.
+3. Open a PR with a clear summary. Use a short GitHub-native title, then flat
+   line-item bullets, then a plain `Validation` label with exact command
+   bullets.
+4. Keep PRs focused and reviewable.
+
+## Reporting issues
+
+If you find a bug or have a feature request, please open an issue with:
+
+1. What you expected to happen
+2. What happened instead
+3. Steps to reproduce
+4. Python version and OS details
+
+## License
+
+By contributing to this project, you agree that your contributions will be
+licensed under the [MIT License](LICENSE).

unicode_animatio-0.0.1/LICENSE

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

unicode_animatio-0.0.1/Makefile

@@ -0,0 +1,61 @@
+REPO_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
+VENV := $(REPO_ROOT)/.venv
+DEV_STAMP := $(VENV)/.baseline-tools-installed
+PYTHON := $(VENV)/bin/python3.11
+PIP := $(PYTHON) -m pip
+PRE_COMMIT := $(PYTHON) -m pre_commit
+PYTEST := $(PYTHON) -m pytest
+RUFF := $(PYTHON) -m ruff
+
+.PHONY: help venv dev-install hooks-install hooks-run fix format format-check lint test check release-check
+
+help:
+	@printf '%s\n' \
+		'Targets:' \
+		'  make dev-install   Create/update .venv and install unicode-animatio with dev extras' \
+		'  make hooks-install Install pre-commit and commit-msg hooks into .git/hooks' \
+		'  make hooks-run     Run pre-commit across the unicode-animatio repo' \
+		'  make fix           Apply Ruff formatting and autofixes' \
+		'  make format        Run Ruff formatter' \
+		'  make format-check  Check formatting without changing files' \
+		'  make lint          Run Ruff lint' \
+		'  make test          Run package pytest suite' \
+		'  make check         Run format-check, lint, and test' \
+		'  make release-check Run package release smoke'
+
+venv:
+	@test -x "$(PYTHON)" || python3.11 -m venv "$(VENV)"
+
+$(DEV_STAMP): pyproject.toml | venv
+	$(PIP) install --upgrade pip setuptools wheel
+	cd "$(REPO_ROOT)" && $(PIP) install -e ".[dev]"
+	@touch "$(DEV_STAMP)"
+
+dev-install: $(DEV_STAMP)
+
+hooks-install: $(DEV_STAMP)
+	$(PRE_COMMIT) install --install-hooks --hook-type pre-commit --hook-type commit-msg
+
+hooks-run: $(DEV_STAMP)
+	$(PRE_COMMIT) run --all-files
+
+fix: $(DEV_STAMP)
+	$(RUFF) format "$(REPO_ROOT)"
+	$(RUFF) check --fix "$(REPO_ROOT)"
+
+format: $(DEV_STAMP)
+	$(RUFF) format "$(REPO_ROOT)"
+
+format-check: $(DEV_STAMP)
+	$(RUFF) format --check "$(REPO_ROOT)"
+
+lint: $(DEV_STAMP)
+	$(RUFF) check "$(REPO_ROOT)"
+
+test: $(DEV_STAMP)
+	PYTHONPATH="$(REPO_ROOT)/src" $(PYTEST) -q "$(REPO_ROOT)/tests"
+
+check: format-check lint test
+
+release-check: $(DEV_STAMP)
+	cd "$(REPO_ROOT)" && $(PYTHON) scripts/release_check.py