bazi 1.0.0__tar.gz

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

@@ -0,0 +1,256 @@
+name: Prepare or Publish Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: Rehearse only, or explicitly publish the tested release
+        type: choice
+        options: [rehearsal, release]
+        default: rehearsal
+        required: true
+
+permissions: {}
+concurrency:
+  group: bazi-release
+  cancel-in-progress: false
+
+jobs:
+  preflight:
+    if: inputs.mode == 'release'
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Require an existing protected release environment
+        env:
+          MODE: ${{ inputs.mode }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.ref }}
+          SHA: ${{ github.sha }}
+        shell: python
+        run: |
+          import json, os, re, urllib.request
+          if (os.environ['MODE'] != 'release' or os.environ['REPOSITORY'] != '0xf3cd/bazi'
+              or os.environ['REF'] != 'refs/heads/main' or not re.fullmatch(r'[0-9a-f]{40}', os.environ['SHA'])):
+            raise SystemExit('Real release requires the main dispatch SHA of 0xf3cd/bazi')
+          def get(path):
+            request = urllib.request.Request('https://api.github.com/repos/0xf3cd/bazi/' + path,
+              headers={'Accept': 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28'})
+            with urllib.request.urlopen(request, timeout=30) as response:
+              return json.load(response)
+          environment = get('environments/release')
+          policies = get('environments/release/deployment-branch-policies?per_page=100')
+          reviewers = [rule for rule in environment.get('protection_rules', [])
+            if rule.get('type') == 'required_reviewers' and any(
+              reviewer.get('type') in ('User', 'Team') and isinstance(reviewer.get('reviewer', {}).get('id'), int)
+              and reviewer['reviewer']['id'] > 0 for reviewer in rule.get('reviewers', []))]
+          if (environment.get('name') != 'release' or not reviewers
+              or environment.get('deployment_branch_policy') != {'protected_branches': False, 'custom_branch_policies': True}
+              or policies.get('total_count') != 1
+              or [(p.get('name'), p.get('type')) for p in policies.get('branch_policies', [])] != [('main', 'branch')]):
+            raise SystemExit('release must have required reviewers and exactly the main branch policy')
+
+  build:
+    needs: [preflight]
+    if: ${{ !cancelled() && (inputs.mode == 'rehearsal' || (inputs.mode == 'release' && needs.preflight.result == 'success')) }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      artifact-id: ${{ steps.upload.outputs.artifact-id }}
+      manifest-sha: ${{ steps.bundle.outputs.manifest-sha }}
+      version: ${{ steps.bundle.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - name: Verify source identity
+        env:
+          SHA: ${{ github.sha }}
+          MODE: ${{ inputs.mode }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.ref }}
+        shell: python
+        run: |
+          import os, re, subprocess
+          mode, sha = os.environ['MODE'], os.environ['SHA']
+          if mode not in ('rehearsal', 'release') or not re.fullmatch(r'[0-9a-f]{40}', sha):
+            raise SystemExit('Invalid release mode or SHA')
+          if mode == 'release' and (os.environ['REPOSITORY'], os.environ['REF']) != ('0xf3cd/bazi', 'refs/heads/main'):
+            raise SystemExit('Real release is main-only')
+          if subprocess.check_output(['git', 'rev-parse', 'HEAD'], text=True).strip() != sha:
+            raise SystemExit('Checkout SHA differs from dispatch SHA')
+      - name: Install development requirements
+        run: |
+          python -m pip install -r Requirements.txt
+          python -m pip install celestial-calendar==0.6.1
+      - name: Run full gate and retain its tested pair
+        run: python run_tests.py -a -v --package-output-dir "$RUNNER_TEMP/bundle/dist"
+      - name: Seal release bundle
+        id: bundle
+        env:
+          SHA: ${{ github.sha }}
+          REPOSITORY: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+          MODE: ${{ inputs.mode }}
+        shell: python
+        run: |
+          import hashlib, json, os, re, shutil, tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          if not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+', version):
+            raise SystemExit('Use a stable three-part release version')
+          bundle = Path(os.environ['RUNNER_TEMP']) / 'bundle'
+          names = {f'bazi-{version}.tar.gz', f'bazi-{version}-py3-none-any.whl'}
+          if {p.name for p in (bundle / 'dist').iterdir()} != names:
+            raise SystemExit('Expected exactly the tested sdist and rebuilt wheel')
+          shutil.copyfile('RELEASE_NOTES.md', bundle / 'RELEASE_NOTES.md')
+          metadata = {'name': 'bazi', 'version': version, 'sha': os.environ['SHA'],
+            'repository': os.environ['REPOSITORY'], 'run_id': os.environ['RUN_ID'], 'mode': os.environ['MODE']}
+          (bundle / 'release.json').write_text(json.dumps(metadata, sort_keys=True) + '\n')
+          files = sorted([*(bundle / 'dist').iterdir(), bundle / 'RELEASE_NOTES.md', bundle / 'release.json'], key=lambda p: p.relative_to(bundle).as_posix())
+          checksums = ''.join(f'{hashlib.sha256(p.read_bytes()).hexdigest()}  {p.relative_to(bundle).as_posix()}\n' for p in files)
+          (bundle / 'SHA256SUMS').write_bytes(checksums.encode('utf-8'))
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
+            output.write(f'version={version}\nmanifest-sha={hashlib.sha256(checksums.encode()).hexdigest()}\n')
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        id: upload
+        with:
+          name: tested-release
+          path: ${{ runner.temp }}/bundle/
+          if-no-files-found: error
+          overwrite: false
+          retention-days: 30
+
+  pypi:
+    needs: [preflight, build]
+    if: inputs.mode == 'release' && needs.preflight.result == 'success' && needs.build.result == 'success' && github.repository == '0xf3cd/bazi' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with: &download
+          artifact-ids: ${{ needs.build.outputs.artifact-id }}
+          path: artifact
+          merge-multiple: true
+          digest-mismatch: error
+      - &verify
+        name: Verify exact same-run bundle
+        env:
+          ARTIFACT_ID: ${{ needs.build.outputs.artifact-id }}
+          MANIFEST_SHA: ${{ needs.build.outputs.manifest-sha }}
+          VERSION: ${{ needs.build.outputs.version }}
+          SHA: ${{ github.sha }}
+          RUN_ID: ${{ github.run_id }}
+          MODE: ${{ inputs.mode }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.ref }}
+        shell: python
+        run: |
+          import hashlib, json, os, re
+          from pathlib import Path
+          version = os.environ['VERSION']
+          if (os.environ['MODE'] != 'release' or os.environ['REPOSITORY'] != '0xf3cd/bazi'
+              or os.environ['REF'] != 'refs/heads/main' or not re.fullmatch(r'[0-9a-f]{40}', os.environ['SHA'])
+              or not re.fullmatch(r'[1-9][0-9]*', os.environ['ARTIFACT_ID'])
+              or not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+', version)):
+            raise SystemExit('Invalid publication identity')
+          root = Path('artifact')
+          expected = {f'dist/bazi-{version}.tar.gz', f'dist/bazi-{version}-py3-none-any.whl', 'release.json', 'RELEASE_NOTES.md'}
+          if ({p.relative_to(root).as_posix() for p in root.rglob('*') if p.is_file()} != expected | {'SHA256SUMS'}
+              or any(p.is_symlink() for p in root.rglob('*'))):
+            raise SystemExit('Unexpected release bundle files')
+          checksums = (root / 'SHA256SUMS').read_bytes()
+          if hashlib.sha256(checksums).hexdigest() != os.environ['MANIFEST_SHA']:
+            raise SystemExit('Manifest differs from tested build')
+          wanted = ''.join(f'{hashlib.sha256((root / name).read_bytes()).hexdigest()}  {name}\n' for name in sorted(expected))
+          if checksums.decode() != wanted:
+            raise SystemExit('Release bundle checksum mismatch')
+          metadata = json.loads((root / 'release.json').read_text())
+          if metadata != {'name': 'bazi', 'version': version, 'sha': os.environ['SHA'], 'repository': '0xf3cd/bazi', 'run_id': os.environ['RUN_ID'], 'mode': 'release'}:
+            raise SystemExit('Release metadata identity mismatch')
+      - name: Reject existing version, tag or release
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        shell: python
+        run: |
+          import os, urllib.error, urllib.request
+          version = os.environ['VERSION']
+          urls = [f'https://pypi.org/pypi/bazi/{version}/json',
+            f'https://api.github.com/repos/0xf3cd/bazi/git/ref/tags/v{version}',
+            f'https://api.github.com/repos/0xf3cd/bazi/releases/tags/v{version}']
+          for url in urls:
+            try:
+              with urllib.request.urlopen(url, timeout=30):
+                pass
+            except urllib.error.HTTPError as error:
+              if error.code == 404:
+                continue
+              raise
+            raise SystemExit('Version, tag or release already exists; deliberate recovery required')
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: artifact/dist/
+          skip-existing: false
+
+  github-release:
+    needs: [preflight, build, pypi]
+    if: inputs.mode == 'release' && needs.preflight.result == 'success' && needs.pypi.result == 'success' && github.repository == '0xf3cd/bazi' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with: *download
+      - *verify
+      - name: Verify PyPI bytes and create the tag and release without overwriting
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+          SHA: ${{ github.sha }}
+          GH_TOKEN: ${{ github.token }}
+        shell: python
+        run: |
+          import hashlib, json, os, urllib.error, urllib.request
+          from pathlib import Path
+          version, sha = os.environ['VERSION'], os.environ['SHA']
+          with urllib.request.urlopen(f'https://pypi.org/pypi/bazi/{version}/json', timeout=30) as response:
+            published = json.load(response)
+          actual = {entry['filename']: entry['digests']['sha256'] for entry in published['urls']}
+          expected = {p.name: hashlib.sha256(p.read_bytes()).hexdigest() for p in Path('artifact/dist').iterdir()}
+          if actual != expected:
+            raise SystemExit('PyPI bytes differ from tested pair')
+          base = 'https://api.github.com/repos/0xf3cd/bazi'
+          headers = {'Authorization': 'Bearer ' + os.environ['GH_TOKEN'], 'Accept': 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28'}
+          for path in (f'/git/ref/tags/v{version}', f'/releases/tags/v{version}'):
+            try:
+              with urllib.request.urlopen(urllib.request.Request(base + path, headers=headers), timeout=30):
+                pass
+            except urllib.error.HTTPError as error:
+              if error.code == 404:
+                continue
+              raise
+            raise SystemExit('Existing tag/release; deliberate recovery required')
+          def post(path, data):
+            request = urllib.request.Request(base + path, data=json.dumps(data).encode(), headers={**headers, 'Content-Type': 'application/json'}, method='POST')
+            with urllib.request.urlopen(request, timeout=30) as response:
+              return json.load(response)
+          post('/git/refs', {'ref': f'refs/tags/v{version}', 'sha': sha})
+          release = post('/releases', {'tag_name': f'v{version}', 'target_commitish': sha,
+            'name': f'bazi {version}', 'body': Path('artifact/RELEASE_NOTES.md').read_text(), 'draft': True})
+          for path in sorted(p for p in Path('artifact').rglob('*') if p.is_file()):
+            url = f'https://uploads.github.com/repos/0xf3cd/bazi/releases/{release["id"]}/assets?name={path.name}'
+            request = urllib.request.Request(url, data=path.read_bytes(), headers={**headers, 'Content-Type': 'application/octet-stream'}, method='POST')
+            with urllib.request.urlopen(request, timeout=60) as response:
+              asset = json.load(response)
+            if asset.get('digest') != 'sha256:' + hashlib.sha256(path.read_bytes()).hexdigest():
+              raise SystemExit('Uploaded GitHub asset digest mismatch; release remains draft')
+          request = urllib.request.Request(base + f'/releases/{release["id"]}', data=b'{"draft":false}', headers={**headers, 'Content-Type': 'application/json'}, method='PATCH')
+          with urllib.request.urlopen(request, timeout=30):
+            pass

bazi-1.0.0/LICENSE

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

bazi-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include pyproject.toml MANIFEST.in LICENSE THIRD_PARTY_NOTICES.md
+include README.md RELEASE_NOTES.md RELEASING.md Requirements.txt ruff.toml
+include run_tests.py run_package_checks.py run_demo.py run_interpreter.py run_relationship_analyzer.py
+recursive-include bazi *.py py.typed
+include bazi/calendar/hko_data/data/jieqi_encoded.bin
+include bazi/calendar/hko_data/data/lunardate_encoded.bin
+include bazi/calendar/hko_data/data/19[0-9][0-9].txt
+include bazi/calendar/hko_data/data/20[0-9][0-9].txt
+include bazi/calendar/hko_data/data/2100.txt
+include bazi/calendar/celestial_data/data/jieqi_moments.txt
+include bazi/calendar/celestial_data/data/lunar_years_algo1.txt
+include bazi/calendar/celestial_data/data/lunar_years_algo2.txt
+include bazi/calendar/celestial_data/SCHEMA.md
+recursive-include tests *.py *.ini *.txt *.json
+include .github/workflows/release.yml
+global-exclude *.py[cod]

bazi-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: bazi
+Version: 1.0.0
+Summary: Four Pillars charts, calendar backends and Bazi relations
+Author: Ningqi Wang (0xf3cd)
+Project-URL: Repository, https://github.com/0xf3cd/bazi
+Project-URL: Issues, https://github.com/0xf3cd/bazi/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Dynamic: license-file
+
+# Bazi
+> 排盘、五行、十神、纳音、刑冲破害、合会
+
+A Python 3.11+ library for Four Pillars charts and their relations. Runtime uses
+only the standard library and five bundled calendar tables; no network access or
+data generation is needed.
+
+## Installation
+
+To build and validate the current checkout and retain an installable pair:
+
+```sh
+python -m pip install -r Requirements.txt
+python run_package_checks.py --output-dir ../bazi-tested
+python -m pip install ../bazi-tested/bazi-1.0.0-py3-none-any.whl
+```
+
+The output directory must be empty and outside the checkout. For a published
+version, install from the registry with `python -m pip install bazi==1.0.0`.
+There is no installed CLI, `src` compatibility package or root-class facade.
+
+```python
+from datetime import datetime
+
+from bazi.bazi import Bazi
+from bazi.bazi_chart import BaziChart
+from bazi.school import BaziConfig
+from bazi.transit_chart import TransitChart
+from bazi.analyzer.relationship import RelationshipAnalyzer
+
+config = BaziConfig.from_values(backend='celestial', precision='day')
+chart = BaziChart(Bazi.create(datetime(2000, 1, 1, 12), 'male', config))
+restored = BaziChart.from_json(chart.json)
+assert restored.json == chart.json
+print(chart.json['pillars'])
+print(TransitChart(chart).at_year(2024))
+print(RelationshipAnalyzer(chart).at_birth.shensha)
+```
+
+Birth times are naive local civil times; timezone-aware inputs are rejected.
+Defaults remain `CELESTIAL` with day precision. `hko` provides date-level calendar
+data; `celestial` and `celestial-algo2` use the bundled astronomical tables.
+Backend differences and supported date ranges are documented in the calendar
+modules; selecting a backend does not install its offline generator.
+
+## Interfaces
+
+Use the defining modules rather than expecting classes at the package root:
+
+| Module | Principal interfaces |
+| --- | --- |
+| `bazi.bazi` | `Bazi`, `BaziGender` |
+| `bazi.bazi_chart` | `BaziChart`, `BaziJson`, JSON restoration with `from_json` |
+| `bazi.school` | `BaziConfig`, `BaziSchool`, precision and school options |
+| `bazi.calendar` | `CalendarBackend`, `CalendarDate`, `CalendarType`, `calendar_utils_of` |
+| `bazi.transit_chart`, `bazi.transits` | `TransitChart`, `TransitSet`, `TransitKind` |
+| `bazi.analyzer.relationship` | `RelationshipAnalyzer` |
+| `bazi.interpreter` | `Interpreter.interpret_tiangan`, `Interpreter.interpret_shishen` |
+| `bazi.defines`, `bazi.utils` | Domain enums and relation utilities, documented in their modules |
+
+Domain names use Pinyin; enums also provide Chinese aliases. JSON retains Chinese
+domain values and records configuration. `py.typed` exposes the inline type hints.
+Private names, offline generation tools and undocumented internals are not a
+promise of a stable public interface.
+
+## Instructions
+
+`Requirements.txt` is the development setup, not the installed library's dependency
+list. It includes test, lint, typing and distribution-verification tools.
+Source-tree mypy also needs `celestial-calendar==0.6.1`, as installed by CPython CI.
+
+```sh
+python -m pip install -r Requirements.txt
+python -m pip install celestial-calendar==0.6.1
+python run_tests.py -a -v
+```
+
+The full gate runs every test (including slow and HKO-data tests), requires 100%
+coverage, runs ruff and strict source mypy, demos, Interpreter, optimized input
+checks, and isolated wheel/sdist-derived-wheel checks. The artifact checks use two
+fresh dependency-free consumers and a separate installed mypy environment.
+The artifact checks (`run_package_checks.py`, `-pkg` and `-a`) may download tools
+and their dependencies from the package index to seed isolated build and typing
+environments, even after the development requirements are installed.
+Builds and consumers live in external temporary directories. Root demo scripts may
+write to `output_data/`; the installed library's read-only behavior is checked separately.
+
+| Flag | Effect |
+| --- | --- |
+| `-a`, `--all` | Full gate; overrides `-nt` and `-k` |
+| `-nt`, `--no-test` | Skip tests and coverage |
+| `-s`, `-hko` | Include slow tests or HKO-data tests |
+| `-k <expression>` | Select pytest tests; ignores `-s` and `-hko` |
+| `-v` | Verbose output |
+| `-c` | Coverage report, also written to `covhtml/` |
+| `-cr <rate>`, `--coverage-rate <rate>` | Minimum coverage (default 100) |
+| `-r`, `--ruff` | Run `ruff check` |
+| `-m`, `-mypy`, `--mypy` | Run source mypy with the runner's strict flags |
+| `-d` | Run both demo scripts |
+| `-i` | Run Interpreter examples |
+| `-osmoke`, `--o-smoke` | Run source public-contract smoke with `python -O` |
+| `-pkg`, `--package` | Run isolated distribution checks |
+| `--package-output-dir <path>` | With `-pkg` or `-a`, retain only the verified sdist and its rebuilt wheel |
+
+A bare `python run_tests.py` omits slow/HKO tests and all optional tasks. It is not
+the full verification gate. Do not run autoformatters; use `ruff check .`.
+
+## Offline Generation
+
+The committed data is read, not regenerated, during packaging or installed use.
+The source tree and sdist contain the raw HKO inputs; the wheel does not.
+Maintainers can regenerate from those sources with `python -m bazi.calendar.hko_data.encoder`
+(`requests` is needed only if inputs must be downloaded), or `python -m bazi.calendar.celestial_data.generator`
+with `celestial-calendar==0.6.1`. These optional tools are not runtime dependencies.
+If an installed table is missing, reinstall the distribution instead.
+
+## License
+
+Author-owned material is available under the standard [MIT License](LICENSE).
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) describes the separate scope of
+calendar data, quotations and other third-party material. Those materials are not
+relicensed by the author's MIT grant. Both notices are included in built artifacts.
+
+See [RELEASE_NOTES.md](RELEASE_NOTES.md) for version changes and
+[RELEASING.md](RELEASING.md) for the manual release procedure.

bazi-1.0.0/README.md

@@ -0,0 +1,125 @@
+# Bazi
+> 排盘、五行、十神、纳音、刑冲破害、合会
+
+A Python 3.11+ library for Four Pillars charts and their relations. Runtime uses
+only the standard library and five bundled calendar tables; no network access or
+data generation is needed.
+
+## Installation
+
+To build and validate the current checkout and retain an installable pair:
+
+```sh
+python -m pip install -r Requirements.txt
+python run_package_checks.py --output-dir ../bazi-tested
+python -m pip install ../bazi-tested/bazi-1.0.0-py3-none-any.whl
+```
+
+The output directory must be empty and outside the checkout. For a published
+version, install from the registry with `python -m pip install bazi==1.0.0`.
+There is no installed CLI, `src` compatibility package or root-class facade.
+
+```python
+from datetime import datetime
+
+from bazi.bazi import Bazi
+from bazi.bazi_chart import BaziChart
+from bazi.school import BaziConfig
+from bazi.transit_chart import TransitChart
+from bazi.analyzer.relationship import RelationshipAnalyzer
+
+config = BaziConfig.from_values(backend='celestial', precision='day')
+chart = BaziChart(Bazi.create(datetime(2000, 1, 1, 12), 'male', config))
+restored = BaziChart.from_json(chart.json)
+assert restored.json == chart.json
+print(chart.json['pillars'])
+print(TransitChart(chart).at_year(2024))
+print(RelationshipAnalyzer(chart).at_birth.shensha)
+```
+
+Birth times are naive local civil times; timezone-aware inputs are rejected.
+Defaults remain `CELESTIAL` with day precision. `hko` provides date-level calendar
+data; `celestial` and `celestial-algo2` use the bundled astronomical tables.
+Backend differences and supported date ranges are documented in the calendar
+modules; selecting a backend does not install its offline generator.
+
+## Interfaces
+
+Use the defining modules rather than expecting classes at the package root:
+
+| Module | Principal interfaces |
+| --- | --- |
+| `bazi.bazi` | `Bazi`, `BaziGender` |
+| `bazi.bazi_chart` | `BaziChart`, `BaziJson`, JSON restoration with `from_json` |
+| `bazi.school` | `BaziConfig`, `BaziSchool`, precision and school options |
+| `bazi.calendar` | `CalendarBackend`, `CalendarDate`, `CalendarType`, `calendar_utils_of` |
+| `bazi.transit_chart`, `bazi.transits` | `TransitChart`, `TransitSet`, `TransitKind` |
+| `bazi.analyzer.relationship` | `RelationshipAnalyzer` |
+| `bazi.interpreter` | `Interpreter.interpret_tiangan`, `Interpreter.interpret_shishen` |
+| `bazi.defines`, `bazi.utils` | Domain enums and relation utilities, documented in their modules |
+
+Domain names use Pinyin; enums also provide Chinese aliases. JSON retains Chinese
+domain values and records configuration. `py.typed` exposes the inline type hints.
+Private names, offline generation tools and undocumented internals are not a
+promise of a stable public interface.
+
+## Instructions
+
+`Requirements.txt` is the development setup, not the installed library's dependency
+list. It includes test, lint, typing and distribution-verification tools.
+Source-tree mypy also needs `celestial-calendar==0.6.1`, as installed by CPython CI.
+
+```sh
+python -m pip install -r Requirements.txt
+python -m pip install celestial-calendar==0.6.1
+python run_tests.py -a -v
+```
+
+The full gate runs every test (including slow and HKO-data tests), requires 100%
+coverage, runs ruff and strict source mypy, demos, Interpreter, optimized input
+checks, and isolated wheel/sdist-derived-wheel checks. The artifact checks use two
+fresh dependency-free consumers and a separate installed mypy environment.
+The artifact checks (`run_package_checks.py`, `-pkg` and `-a`) may download tools
+and their dependencies from the package index to seed isolated build and typing
+environments, even after the development requirements are installed.
+Builds and consumers live in external temporary directories. Root demo scripts may
+write to `output_data/`; the installed library's read-only behavior is checked separately.
+
+| Flag | Effect |
+| --- | --- |
+| `-a`, `--all` | Full gate; overrides `-nt` and `-k` |
+| `-nt`, `--no-test` | Skip tests and coverage |
+| `-s`, `-hko` | Include slow tests or HKO-data tests |
+| `-k <expression>` | Select pytest tests; ignores `-s` and `-hko` |
+| `-v` | Verbose output |
+| `-c` | Coverage report, also written to `covhtml/` |
+| `-cr <rate>`, `--coverage-rate <rate>` | Minimum coverage (default 100) |
+| `-r`, `--ruff` | Run `ruff check` |
+| `-m`, `-mypy`, `--mypy` | Run source mypy with the runner's strict flags |
+| `-d` | Run both demo scripts |
+| `-i` | Run Interpreter examples |
+| `-osmoke`, `--o-smoke` | Run source public-contract smoke with `python -O` |
+| `-pkg`, `--package` | Run isolated distribution checks |
+| `--package-output-dir <path>` | With `-pkg` or `-a`, retain only the verified sdist and its rebuilt wheel |
+
+A bare `python run_tests.py` omits slow/HKO tests and all optional tasks. It is not
+the full verification gate. Do not run autoformatters; use `ruff check .`.
+
+## Offline Generation
+
+The committed data is read, not regenerated, during packaging or installed use.
+The source tree and sdist contain the raw HKO inputs; the wheel does not.
+Maintainers can regenerate from those sources with `python -m bazi.calendar.hko_data.encoder`
+(`requests` is needed only if inputs must be downloaded), or `python -m bazi.calendar.celestial_data.generator`
+with `celestial-calendar==0.6.1`. These optional tools are not runtime dependencies.
+If an installed table is missing, reinstall the distribution instead.
+
+## License
+
+Author-owned material is available under the standard [MIT License](LICENSE).
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) describes the separate scope of
+calendar data, quotations and other third-party material. Those materials are not
+relicensed by the author's MIT grant. Both notices are included in built artifacts.
+
+See [RELEASE_NOTES.md](RELEASE_NOTES.md) for version changes and
+[RELEASING.md](RELEASING.md) for the manual release procedure.

bazi-1.0.0/RELEASE_NOTES.md

@@ -0,0 +1,16 @@
+# bazi 1.0.0
+
+- Installable `bazi` package with modular imports, Python 3.11+, inline typing and
+  no runtime dependencies. Source imports now use `bazi.*`, not `src.*`.
+- The wheel bundles the two encoded HKO tables and three celestial tables. The
+  source archive also includes raw HKO inputs and source-verification tests.
+- Existing calendar backends, rules, school defaults, JSON restoration, transits,
+  relationship analysis and Interpreter remain available without data regeneration.
+- Standard MIT permission covers author-owned material; third-party notices state
+  the separate scope of embedded data and quotations.
+- The manual release workflow defaults to rehearsal. Publication requires protected
+  environment approval and publishes only the tested sdist and its rebuilt wheel.
+
+No `src` shim, root-class facade or installed command-line entrypoint is provided.
+See `README.md` for principal module interfaces and `RELEASING.md` for release
+prerequisites.

bazi-1.0.0/RELEASING.md

@@ -0,0 +1,65 @@
+# Releasing bazi
+
+The manual `release.yml` workflow prepares one verified sdist and its rebuilt
+wheel. The direct wheel is only a validation control. There are no push/tag
+publication triggers and no arbitrary ref, registry or artifact inputs.
+
+## Prerequisites
+
+The owner must separately confirm PyPI account/project eligibility for `bazi` and
+configure a Trusted Publisher (or pending publisher) for owner `0xf3cd`, repository
+`bazi`, workflow `release.yml`, environment `release`. A public name lookup does not
+reserve the name or establish account readiness. No API token belongs in this repository.
+
+Create the GitHub environment `release` explicitly, with at least one required
+reviewer and a custom deployment policy containing exactly branch `main` (not a
+tag or wildcard). Personal owner approval is valid; allow self-review if that is
+the intended approval path. This workflow does not require two people. Only the
+publishing jobs bind the environment; an earlier read-only REST preflight fails
+closed if the environment, reviewer rule or exact branch policy is missing.
+
+The workflow must exist on the default branch before it can be dispatched.
+
+## Rehearsal
+
+1. Review `pyproject.toml`'s static version and `RELEASE_NOTES.md`. Merge the intended
+   release changes to main before dispatch; do not create a tag yet.
+2. Dispatch `Prepare or Publish Release` on main with `mode=rehearsal` (the default).
+   This runs the full source and artifact gates at the dispatch SHA, with no
+   environment binding, write permission or OIDC permission.
+3. Inspect the run's `tested-release` artifact: exactly one wheel and sdist under
+   `dist/`, release notes, `release.json`, and `SHA256SUMS`. Confirm the source SHA,
+   run ID, version, licenses, file contents and checksums. Artifacts expire after
+   30 days; retain the approved bytes before expiry when recovery may be needed.
+
+Run a rehearsal before authorizing real publication. Local artifact and offline
+policy tests do not substitute for it or prove GitHub/PyPI configuration is ready.
+
+## Real Release
+
+1. Obtain separate authorization and dispatch main with `mode=release`. Confirm
+   that the dispatch SHA is the intended release commit. The real run performs its
+   own full verification; it never accepts an artifact ID from a previous run.
+2. Approve the protected environment for PyPI after checking the run's verified
+   bundle. The OIDC-only job downloads the exact immutable artifact ID produced by
+   this run, verifies checksums and identity, and rejects existing versions/tags/releases.
+3. After PyPI succeeds, approve the GitHub Release job. This contents-write-only job
+   checks PyPI hashes, creates `v<version>` at the tested SHA, creates a draft release,
+   uploads the same bytes and notices, checks asset digests, then publishes the draft.
+   Neither privileged job checks out, builds, installs or imports repository code.
+4. Independently download both published artifacts from PyPI and GitHub and compare
+   them to the retained checksums. Confirm the tag SHA and release metadata. Install
+   the published wheel in a fresh environment and repeat the consumer smoke.
+   Verify the actual PyPI Trusted Publisher identity/attestations too.
+
+## Partial Failure
+
+Publication is not transactional. An existing version, tag or release is an error;
+there is no overwrite, tag move or `skip-existing` recovery. Do not rerun the whole
+workflow to bypass a partial failure and do not rebuild the accepted bytes.
+
+If PyPI has the pair but GitHub failed, stop and inspect the retained same-run
+bundle, PyPI digests, tag SHA and any draft release/assets. The owner must approve
+a targeted recovery of only the missing operations using those exact bytes. If a
+tag or draft already exists, verify it rather than moving or replacing it. A digest
+mismatch requires investigation, not automatic deletion, a version bump or a new upload.

bazi-1.0.0/Requirements.txt

@@ -0,0 +1,17 @@
+colorama==0.4.6
+psutil==7.2.2
+tzdata==2026.3
+pytest==9.1.1
+ruff==0.16.1
+coverage==7.16.0
+mypy==2.3.1
+emoji==2.15.0
+types-colorama==0.4.15.20260508
+types-psutil==7.2.2.20260906
+
+# Distribution builds and artifact verification (not runtime dependencies).
+build==1.6.1
+setuptools==84.0.0
+twine==7.0.0
+PyYAML==6.0.3
+types-PyYAML==6.0.12.20250915