steamify 2.0.0__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {steamify-2.0.0 → steamify-2.1.0}/.github/workflows/ci.yaml +5 -8
  2. {steamify-2.0.0 → steamify-2.1.0}/.github/workflows/release.yaml +22 -16
  3. steamify-2.1.0/.python-version +1 -0
  4. steamify-2.1.0/AGENTS.md +81 -0
  5. {steamify-2.0.0 → steamify-2.1.0}/CHANGELOG.md +78 -4
  6. {steamify-2.0.0 → steamify-2.1.0}/CODE_OF_CONDUCT.md +13 -0
  7. {steamify-2.0.0 → steamify-2.1.0}/CONTRIBUTING.md +49 -15
  8. {steamify-2.0.0 → steamify-2.1.0}/PKG-INFO +42 -32
  9. {steamify-2.0.0 → steamify-2.1.0}/README.md +38 -29
  10. steamify-2.1.0/assets/logo.svg +8 -0
  11. {steamify-2.0.0 → steamify-2.1.0}/cliff.toml +2 -0
  12. {steamify-2.0.0 → steamify-2.1.0}/justfile +5 -9
  13. steamify-2.1.0/pyproject.toml +93 -0
  14. steamify-2.1.0/src/steamify/__main__.py +112 -0
  15. {steamify-2.0.0 → steamify-2.1.0}/src/steamify/markdown.py +1 -1
  16. {steamify-2.0.0 → steamify-2.1.0}/src/steamify/steam.py +1 -1
  17. steamify-2.1.0/tests/test_main.py +85 -0
  18. steamify-2.1.0/uv.lock +810 -0
  19. steamify-2.0.0/.github/labels.yaml +0 -59
  20. steamify-2.0.0/.github/workflows/labels.yaml +0 -34
  21. steamify-2.0.0/.python-version +0 -1
  22. steamify-2.0.0/CLAUDE.md +0 -125
  23. steamify-2.0.0/pyproject.toml +0 -88
  24. steamify-2.0.0/uv.lock +0 -434
  25. {steamify-2.0.0 → steamify-2.1.0}/.editorconfig +0 -0
  26. {steamify-2.0.0 → steamify-2.1.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  27. {steamify-2.0.0 → steamify-2.1.0}/.gitignore +0 -0
  28. {steamify-2.0.0 → steamify-2.1.0}/LICENSE +0 -0
  29. {steamify-2.0.0 → steamify-2.1.0}/SECURITY.md +0 -0
  30. {steamify-2.0.0 → steamify-2.1.0}/src/steamify/__init__.py +0 -0
  31. {steamify-2.0.0 → steamify-2.1.0}/tests/test_markdown.py +0 -0
  32. {steamify-2.0.0 → steamify-2.1.0}/tests/test_steam.py +0 -0
@@ -7,8 +7,8 @@ on:
7
7
  workflow_dispatch:
8
8
 
9
9
  concurrency:
10
- group: ci-${{ github.workflow }}-${{ github.ref }}
11
- cancel-in-progress: ${{ github.event_name == 'pull_request' }}
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
12
12
 
13
13
  permissions:
14
14
  contents: read
@@ -18,15 +18,15 @@ jobs:
18
18
  runs-on: ubuntu-24.04-arm
19
19
  steps:
20
20
  - name: Checkout repository
21
- uses: actions/checkout@v6
21
+ uses: actions/checkout@v7
22
22
 
23
23
  - name: Install just
24
24
  uses: extractions/setup-just@v4
25
25
 
26
26
  - name: Install uv
27
- uses: astral-sh/setup-uv@v6
27
+ uses: astral-sh/setup-uv@v10.1.0
28
28
  with:
29
- python-version: "3.13"
29
+ python-version: "3.14"
30
30
 
31
31
  - name: Install dependencies
32
32
  run: just install
@@ -34,8 +34,5 @@ jobs:
34
34
  - name: Run linters
35
35
  run: just lint
36
36
 
37
- - name: Run audit
38
- run: just audit
39
-
40
37
  - name: Run tests
41
38
  run: just test
@@ -1,6 +1,3 @@
1
- # Requires GitHub secrets
2
- # - PYPI_TOKEN
3
-
4
1
  name: Release
5
2
 
6
3
  on:
@@ -13,14 +10,18 @@ on:
13
10
  permissions:
14
11
  contents: write
15
12
 
13
+ concurrency:
14
+ group: release
15
+ cancel-in-progress: false
16
+
16
17
  jobs:
17
18
  tag:
18
- runs-on: ubuntu-latest
19
+ runs-on: ubuntu-24.04-arm
19
20
  outputs:
20
21
  tag: v${{ steps.version.outputs.version }}
21
22
  steps:
22
23
  - name: Checkout repository
23
- uses: actions/checkout@v6
24
+ uses: actions/checkout@v7
24
25
  with:
25
26
  fetch-depth: 0
26
27
 
@@ -33,20 +34,22 @@ jobs:
33
34
  run: echo "$RUNNER_TEMP/git-cliff/bin" >> "$GITHUB_PATH"
34
35
 
35
36
  - name: Install uv
36
- uses: astral-sh/setup-uv@v6
37
+ uses: astral-sh/setup-uv@v10.1.0
37
38
  with:
38
- python-version: "3.13"
39
+ python-version: "3.14"
39
40
 
40
41
  - name: Resolve version
41
42
  id: version
42
43
  run: |
43
44
  if [[ -n "${{ github.event.inputs.version }}" ]]; then
44
45
  VERSION="${{ github.event.inputs.version }}"
46
+ VERSION="${VERSION#v}"
45
47
  else
46
48
  VERSION=$(git-cliff --bumped-version)
47
49
  VERSION="${VERSION#v}"
48
50
  fi
49
51
  echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
52
+ echo "resolved version: ${VERSION}"
50
53
 
51
54
  - name: Update version
52
55
  run: uv version "${{ steps.version.outputs.version }}"
@@ -70,42 +73,45 @@ jobs:
70
73
 
71
74
  release:
72
75
  needs: tag
73
- runs-on: ubuntu-latest
76
+ runs-on: ubuntu-24.04-arm
74
77
  steps:
75
78
  - name: Checkout repository
76
- uses: actions/checkout@v6
79
+ uses: actions/checkout@v7
77
80
  with:
78
81
  ref: ${{ needs.tag.outputs.tag }}
79
82
  fetch-depth: 0
80
83
 
81
- - name: Generate Changelog
84
+ - name: Generate changelog
82
85
  uses: orhun/git-cliff-action@v4
83
86
  id: changelog
84
87
  with:
85
88
  args: --latest --strip header
86
89
 
87
90
  - name: Create GitHub Release
88
- uses: softprops/action-gh-release@v2
91
+ uses: softprops/action-gh-release@v3
89
92
  with:
90
93
  tag_name: ${{ needs.tag.outputs.tag }}
91
94
  body: ${{ steps.changelog.outputs.content }}
92
95
 
93
96
  publish:
94
97
  needs: [tag, release]
95
- runs-on: ubuntu-latest
98
+ runs-on: ubuntu-24.04-arm
99
+ permissions:
100
+ contents: read
101
+ id-token: write
96
102
  steps:
97
103
  - name: Checkout repository
98
- uses: actions/checkout@v6
104
+ uses: actions/checkout@v7
99
105
  with:
100
106
  ref: ${{ needs.tag.outputs.tag }}
101
107
 
102
108
  - name: Install uv
103
- uses: astral-sh/setup-uv@v6
109
+ uses: astral-sh/setup-uv@v10.1.0
104
110
  with:
105
- python-version: "3.13"
111
+ python-version: "3.14"
106
112
 
107
113
  - name: Build
108
114
  run: uv build
109
115
 
110
116
  - name: Publish to PyPI
111
- run: uv publish --token ${{ secrets.PYPI_TOKEN }}
117
+ run: uv publish --trusted-publishing always
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,81 @@
1
+ # AGENTS.md
2
+
3
+ `steamify` is a published PyPI library that converts Markdown to Steam's BBCode-style markup and
4
+ back, exposing exactly two public functions, `to_steam` and `to_markdown`. `src/steamify/__main__.py`
5
+ exposes the same pair as the `steamify` console script (also `python -m steamify`), and is I/O only.
6
+ `README.md` lists the supported constructs; `CONTRIBUTING.md` covers commands, branches, commits, and
7
+ CI.
8
+
9
+ ## Constraints
10
+
11
+ - **Zero runtime dependencies is a product constraint, not an accident.** Everything is built on `re`
12
+ and the standard library. Do not add a runtime dependency without the maintainer asking for one
13
+ - **`requires-python = ">=3.10"` is the supported floor**, even though `.python-version` and CI
14
+ both pin 3.14. `just format` enforces it through ruff's pyupgrade rules
15
+ - **Run `just check` before proposing a change is done** (`just --list` for the rest). Type checking
16
+ is `ty`, not mypy
17
+ - **Never hand-edit `version` in `pyproject.toml` or `CHANGELOG.md`.** The Release workflow
18
+ (`workflow_dispatch` only) derives both from the commit history with git-cliff
19
+ - **`.no-tests` is an untracked sentinel that makes `just test` a no-op.** Do not create it unless
20
+ deliberately silencing the suite
21
+ - Ruff runs `select = ["ALL"]` - assume a new rule will fire and run `just format` before `just lint`
22
+ - `just format`, `just lint` and `just test` all run through `uv run` (project venv), so the versions
23
+ pinned in `[dependency-groups]` are the ones that run
24
+ - Coverage is reported, not gated - there is no `fail_under`, so `term-missing` output blocks nothing
25
+ - **`__main__.py` is a text-in/text-out shim, not a third pipeline.** Conversion logic belongs in
26
+ `steam.py` / `markdown.py`; `main(argv=None) -> int` only reads, converts, writes, and returns an
27
+ exit code. `--encoding` governs the files **and** stdin/stdout, which is why stdin/stdout go
28
+ through `sys.stdin.buffer` / `sys.stdout.buffer` instead of the text layers
29
+ - `__init__.py` sets `__version__` from `importlib.metadata.version("steamify")`, so the package must
30
+ be installed (editable is fine) for import to work
31
+
32
+ ## Invariants
33
+
34
+ `steam.py` (Markdown -> Steam) and `markdown.py` (Steam -> Markdown) are deliberate mirror images of
35
+ each other. When editing one, check whether the other needs the symmetric change.
36
+
37
+ - **The `_try_convert_*` contract** - each returns `True` if it consumed the line and `False` if it
38
+ did not apply, and `_process_line` relies on that to short-circuit. Order matters: in `markdown.py`
39
+ the chain is a single `or` expression, and code-block detection must come first so markup inside a
40
+ `[code]` block is never interpreted
41
+ - **The `@@CODE{n}@@` sandwich** - inside `_convert_inline_elements`, `_convert_inline_code_spans`
42
+ pulls every code span out and leaves a sentinel, the other inline conversions run on the
43
+ sentinel-bearing text, then `_render_inline_code_spans` substitutes the originals back wrapped in
44
+ the target syntax. This is what stops `**bold**` inside `` `code` `` from being mangled, so any new
45
+ inline conversion must be inserted **between** the extract and render steps or code spans stop
46
+ being protected
47
+ - **`list_stack` diverges between the modules** - it is a `list[tuple[str, int]]` in both, but the
48
+ second element is the source indent width in spaces in `steam.py`, used to decide
49
+ open/close/dedent, and the running item counter in `markdown.py`, used to number `[olist]` entries
50
+
51
+ ### Deliberate Asymmetries
52
+
53
+ These look like bugs but are intended; tests lock them in:
54
+
55
+ - `to_steam` clamps headings to h1-h3 because Steam only supports three heading levels, while
56
+ `to_markdown` maps `[h1]`-`[h6]` to `#`-`######`
57
+ - Steam-only tags with no Markdown equivalent pass through verbatim rather than being stripped - see
58
+ `test_unmappable_tags_pass_through`
59
+ - The round-trip guarantee is convergence, not identity: `to_steam(to_markdown(steam)) == steam`
60
+ after the first pass, enforced by `test_round_trip_is_stable`. Markdown -> Steam -> Markdown is not
61
+ required to return the original string
62
+
63
+ ## Adding a New Construct
64
+
65
+ 1. Add the compiled pattern to the `_PATTERN_*` block at the top of the module, not inline in a
66
+ function
67
+ 2. Block-level: write another `_try_convert_*` and insert it at the right position in the
68
+ `_process_line` chain, never ahead of code-block detection
69
+ 3. Inline: add the conversion between the extract and render halves of `_convert_inline_elements`
70
+ 4. Make the symmetric change in the sibling module, or establish why it does not apply
71
+ 5. Add cases to the existing `test_complex_scenarios` / `test_edge_cases` parametrize blocks
72
+
73
+ ## Tests
74
+
75
+ The suite is **white-box**: private functions are imported directly by name and tested individually,
76
+ alongside end-to-end `to_steam` / `to_markdown` cases. Renaming a private helper breaks tests, which
77
+ is intentional. Heavy use of `@pytest.mark.parametrize` with `(input, expected)` tuples - add cases
78
+ to an existing parametrize list rather than writing a new test function when the shape fits.
79
+
80
+ `tests/test_main.py` covers the CLI by calling `main()` directly rather than spawning subprocesses:
81
+ stdin/stdout, file to file, `--to-markdown`, `--encoding`, and the exit-1 error path.
@@ -2,6 +2,76 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [2.1.0] - 2026-11-11
6
+
7
+ ### Build
8
+
9
+ - Standardize the pyproject configuration
10
+ - Standardize just recipes
11
+ - Drop pyupgrade in favor of ruff
12
+ - **deps**: Update dependencies
13
+ - Add python 3.14 classifier
14
+ - Update dependencies
15
+ - Bump local python to 3.14
16
+ - Update dependencies
17
+
18
+ ### CI/CD
19
+
20
+ - Pin workflow python to 3.14
21
+ - Pin setup-uv to v10.1.0
22
+ - Drop label sync in favor of terraform
23
+
24
+ ### Documentation
25
+
26
+ - Describe the standardized recipes
27
+ - Describe format without pyupgrade
28
+ - Move agent instructions from CLAUDE.md to AGENTS.md
29
+ - Update python version references to 3.14
30
+ - Add logo to readme
31
+ - Correct python version references
32
+ - Rewrite CLAUDE.md from scratch
33
+ - Regenerate CLAUDE.md and add AGENTS.md
34
+ - Correct release publishing note to trusted publishing
35
+ - **release**: Drop trusted publishing header comments
36
+
37
+ ### Features
38
+
39
+ - **cli**: Add argparse command-line interface / 新增 argparse 命令行接口
40
+
41
+ ### Miscellaneous
42
+
43
+ - Drop unused noqa comments
44
+ - **assets**: Drop svg repo attribution comments
45
+ - **assets**: Recolor logo to steam blue
46
+ - **justfile**: Upgrade dependencies on install
47
+ - Repository housekeeping
48
+ - Symlink AGENTS.md to CLAUDE.md
49
+
50
+ ### Refactor
51
+
52
+ - **justfile**: Standardize recipe names and ordering
53
+
54
+ ## [2.0.1] - 2026-09-04
55
+
56
+ ### Build
57
+
58
+ - Sync lockfile to 2.0.0
59
+
60
+ ### CI/CD
61
+
62
+ - Publish to pypi via trusted publishing instead of a token
63
+
64
+ ### Documentation
65
+
66
+ - Restore per-direction feature lists
67
+ - Match package description to the readme overview
68
+ - Tighten readme overview and drop round-tripping section
69
+ - Trim readme to overview, round-tripping, and usage
70
+
71
+ ### Release
72
+
73
+ - V2.0.1
74
+
5
75
  ## [2.0.0] - 2026-09-04
6
76
 
7
77
  ### Build
@@ -54,6 +124,10 @@ All notable changes to this project will be documented in this file.
54
124
 
55
125
  - Rename package to steamify and split pipeline by direction
56
126
 
127
+ ### Release
128
+
129
+ - V2.0.0
130
+
57
131
  ## [1.2.4] - 2026-05-31
58
132
 
59
133
  ### Build
@@ -111,14 +185,14 @@ All notable changes to this project will be documented in this file.
111
185
  - Add update command to justfile and CLAUDE.md
112
186
  - Update .gitignore and remove .python-version
113
187
 
114
- ### Release
115
-
116
- - V1.2.2
117
-
118
188
  ### Style
119
189
 
120
190
  - Format justfile and .editorconfig indentation
121
191
 
192
+ ### Release
193
+
194
+ - V1.2.2
195
+
122
196
  ## [1.2.1] - 2026-03-29
123
197
 
124
198
  ### Build
@@ -1,5 +1,18 @@
1
1
  # Contributor Covenant Code of Conduct
2
2
 
3
+ - [Contributor Covenant Code of Conduct](#contributor-covenant-code-of-conduct)
4
+ - [Our Pledge](#our-pledge)
5
+ - [Our Standards](#our-standards)
6
+ - [Enforcement Responsibilities](#enforcement-responsibilities)
7
+ - [Scope](#scope)
8
+ - [Enforcement](#enforcement)
9
+ - [Enforcement Guidelines](#enforcement-guidelines)
10
+ - [Correction](#correction)
11
+ - [Warning](#warning)
12
+ - [Temporary Ban](#temporary-ban)
13
+ - [Permanent Ban](#permanent-ban)
14
+ - [Attribution](#attribution)
15
+
3
16
  ## Our Pledge
4
17
 
5
18
  We as members, contributors, and leaders pledge to make participation in our community a
@@ -1,8 +1,20 @@
1
1
  # Contributing
2
2
 
3
+ - [Contributing](#contributing)
4
+ - [Reporting Bugs](#reporting-bugs)
5
+ - [How to Submit a Bug Report](#how-to-submit-a-bug-report)
6
+ - [Suggesting Enhancements](#suggesting-enhancements)
7
+ - [How to Submit an Enhancement](#how-to-submit-an-enhancement)
8
+ - [Code Contributions](#code-contributions)
9
+ - [Local Development](#local-development)
10
+ - [CI/CD](#cicd)
11
+ - [Branches](#branches)
12
+ - [Commits](#commits)
13
+ - [Pull Requests](#pull-requests)
14
+
3
15
  Thank you for taking the time to contribute.
4
16
 
5
- These guidelines are intended to make contributions consistent and easy to review across repositories. They are guidance, not hard rules, and maintainers may adapt them when needed.
17
+ These guidelines are intended to make contributions consistent and easy to review across repositories. They are guidance, not hard instructions, and maintainers may adapt them when needed.
6
18
 
7
19
  ## Reporting Bugs
8
20
 
@@ -15,7 +27,7 @@ When opening a bug report, include enough context for someone else to reproduce
15
27
 
16
28
  ### How to Submit a Bug Report
17
29
 
18
- Use the bug issue template and provide the following:
30
+ Open a bug report and provide the following:
19
31
 
20
32
  - A clear, descriptive title
21
33
  - Reproduction steps (minimal and reliable if possible)
@@ -34,7 +46,7 @@ Enhancement requests can include new features, changes to existing behavior, usa
34
46
 
35
47
  ### How to Submit an Enhancement
36
48
 
37
- Use the feature request template and provide the following:
49
+ Open a feature request and provide the following:
38
50
 
39
51
  - A clear problem statement
40
52
  - The proposed solution
@@ -47,15 +59,37 @@ Concrete examples, API sketches, UI mockups, or references are helpful when rele
47
59
 
48
60
  ### Local Development
49
61
 
50
- 1. Fork the repository and create a branch for your change.
51
- 2. Set up the project using the repository's README or development docs.
52
- 3. Run the project's tests and quality checks locally before opening a pull request.
62
+ This repo needs [uv](https://docs.astral.sh/uv), which manages Python 3.14 for you, and `just`.
63
+
64
+ This project uses [`just`](https://github.com/casey/just) as its task runner. Run `just --list` for the full set; these are the ones you need day to day:
53
65
 
54
- If the repository has helper scripts or a task runner, use those documented commands.
66
+ | Command | What it does |
67
+ | --- | --- |
68
+ | `just install` | Installs every dependency group and extra into the project virtualenv |
69
+ | `just format` | Rewrites the sources in place: applies ruff's safe fixes, including its pyupgrade rules for Python 3.10+, and formatting |
70
+ | `just lint` | Lints the project with ruff and type-checks it with ty, without changing any file |
71
+ | `just test` | Runs the test suite, skipped when the `.no-tests` sentinel is present |
72
+ | `just check` | Runs `lint` then `test` in sequence |
73
+ | `just update` | Refreshes the lockfile to the latest resolvable versions, then raises the dependency lower bounds in `pyproject.toml` with uv-upsync |
74
+
75
+ 1. Fork the repository and clone your fork locally
76
+ 2. Create a branch using the naming pattern described below
77
+ 3. Make your changes, then run `just check` before opening a pull request
55
78
 
56
79
  > [!IMPORTANT]
57
80
  > Behavioral code changes should include or update tests.
58
81
 
82
+ ### CI/CD
83
+
84
+ Workflows live in `.github/workflows`:
85
+
86
+ | Workflow | Trigger | What it does |
87
+ | --- | --- | --- |
88
+ | CI | Push to `main`, pull requests, `workflow_dispatch` | Single `ci` job on `ubuntu-24.04-arm`; installs `just` and uv pinned to Python 3.14, installs the project dependencies, then lints, type-checks and tests the project |
89
+ | Release | `workflow_dispatch` (optional `version` input) | Three chained jobs on `ubuntu-24.04-arm`: `tag` takes the version from the `version` input or derives the next one from the commit history with git-cliff, bumps the project version, regenerates `CHANGELOG.md` and pushes the release commit and its tag to `main`; `release` (needs `tag`) publishes the GitHub Release with the generated notes; `publish` (needs `tag` and `release`) builds the package and uploads it to PyPI via trusted publishing |
90
+
91
+ CI must be green before a pull request is merged.
92
+
59
93
  ### Branches
60
94
 
61
95
  Branch names follow the pattern `<type>/<short-description>` using the same type prefixes as commits.
@@ -70,7 +104,7 @@ docs/update-sync-flow-diagram
70
104
  refactor/mcps-schema-alignment
71
105
  ```
72
106
 
73
- Split a branch that covers multiple unrelated changes. One concern per branch makes review and bisect much easier.
107
+ A branch covering multiple unrelated changes should be split. One concern per branch makes review and bisect much easier.
74
108
 
75
109
  ### Commits
76
110
 
@@ -78,7 +112,7 @@ Use clear, focused commits with descriptive messages.
78
112
 
79
113
  This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
80
114
 
81
- #### Format
115
+ **Format**
82
116
 
83
117
  ```
84
118
  <type>(<scope>): <subject>
@@ -86,12 +120,12 @@ This project follows [Conventional Commits](https://www.conventionalcommits.org/
86
120
  [optional body]
87
121
  ```
88
122
 
89
- - `type`: one of the prefixes from the table below
90
- - `scope`: the module, command, or area being changed (e.g. `sync`, `mcps`, `github`, `landing`, `config`); omit when the change is truly cross-cutting
91
- - `subject`: imperative mood, lowercase, no trailing period, 72 characters or fewer
92
- - `body`: optional; use it to explain *why*, not *what*; wrap at 72 characters
123
+ - **type** - one of the prefixes from the table below
124
+ - **scope** - the module, command, or area being changed (e.g. `sync`, `mcps`, `github`, `landing`, `config`); omit when the change is truly cross-cutting
125
+ - **subject** - imperative mood, lowercase, no trailing period, 72 characters or fewer
126
+ - **body** - optional; use it to explain *why*, not *what*; wrap at 72 characters
93
127
 
94
- #### Type Prefixes
128
+ **Type prefixes**
95
129
 
96
130
  | Prefix | When to use |
97
131
  | ---------- | ------------------------------------------------------------------------------------------------------- |
@@ -108,7 +142,7 @@ This project follows [Conventional Commits](https://www.conventionalcommits.org/
108
142
  | `design` | Changes to visual or UI design assets and layout |
109
143
  | `revert` | Reverts a previous commit (reference the reverted commit hash in the body) |
110
144
 
111
- #### Examples
145
+ **Examples**
112
146
 
113
147
  ```
114
148
  feat(sync): support skills source sub-directory selection
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: steamify
3
- Version: 2.0.0
4
- Summary: A lightweight package for converting Markdown into Steam-compatible markup, and back again.
3
+ Version: 2.1.0
4
+ Summary: A lightweight package with zero runtime dependencies for converting Markdown into Steam-compatible markup, and back again.
5
5
  Project-URL: Homepage, https://github.com/pivoshenko/steamify
6
6
  Project-URL: Repository, https://github.com/pivoshenko/steamify
7
7
  Author-email: Volodymyr Pivoshenko <contact@pivoshenko.dev>
@@ -17,11 +17,12 @@ Classifier: License :: OSI Approved :: MIT License
17
17
  Classifier: Natural Language :: English
18
18
  Classifier: Operating System :: OS Independent
19
19
  Classifier: Programming Language :: Python
20
- Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
21
  Classifier: Programming Language :: Python :: 3.10
22
22
  Classifier: Programming Language :: Python :: 3.11
23
23
  Classifier: Programming Language :: Python :: 3.12
24
24
  Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
25
26
  Classifier: Topic :: Scientific/Engineering
26
27
  Classifier: Topic :: Software Development
27
28
  Classifier: Topic :: Software Development :: Libraries
@@ -29,7 +30,10 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
29
30
  Requires-Python: >=3.10
30
31
  Description-Content-Type: text/markdown
31
32
 
32
- # Steamify
33
+ <h1 align="left">
34
+ <img src="https://raw.githubusercontent.com/pivoshenko/steamify/main/assets/logo.svg" alt="" height="40" align="left" style="vertical-align: middle; margin-right: 12px;">
35
+ Steamify
36
+ </h1>
33
37
 
34
38
  <p align="left">
35
39
  <a href="https://pypi.org/project/steamify">
@@ -51,46 +55,32 @@ Description-Content-Type: text/markdown
51
55
 
52
56
  ## Overview
53
57
 
54
- A lightweight package for converting Markdown into Steam-compatible markup, and back again.
55
-
56
- ### About the Name
57
-
58
- *Steamify* is what the package does: it takes Markdown and makes it Steam-flavoured, and it reads Steam markup back into Markdown. It was extracted from [Ihroteka](https://ihroteka.com), a personal game-library app, and released standalone.
58
+ A lightweight package with zero runtime dependencies for converting Markdown into Steam-compatible
59
+ markup, and back again.
59
60
 
60
61
  ## Features
61
62
 
62
- Zero runtime dependencies, and conversion in both directions.
63
+ ### Markdown to Steam
63
64
 
64
- ### Markdown -> Steam
65
-
66
- - Headings (`#` to `######`) -> `[h1]` to `[h3]`, since Steam caps at three levels
65
+ - Headings (`#` through `######`) to `[h1]` through `[h3]`, since Steam caps at three levels
67
66
  - Bold, italic, strikethrough, inline code
68
- - Links and images -> `[url]` / `[img]`
67
+ - Links and images to `[url]` / `[img]`
69
68
  - Ordered and unordered lists (nested)
70
69
  - Blockquotes (nested)
71
- - Fenced code blocks -> `[code]`
72
- - Horizontal rules -> `[hr][/hr]`
70
+ - Fenced code blocks to `[code]`
71
+ - Horizontal rules to `[hr][/hr]`
73
72
 
74
- ### Steam -> Markdown
73
+ ### Steam to Markdown
75
74
 
76
- - `[h1]` to `[h6]` -> `#` to `######`
77
- - `[b]`, `[i]`, `[strike]`, `[code]` -> `**`, `*`, `~~`, backticks
78
- - `[url]` / `[img]` -> Markdown links and images
79
- - `[list]` / `[olist]` (nested) -> `-` / `1.`
80
- - `[quote]` (nested) -> `>`
81
- - `[hr][/hr]` -> `---`
75
+ - `[h1]` through `[h6]` to `#` through `######`
76
+ - `[b]`, `[i]`, `[strike]`, `[code]` to `**`, `*`, `~~`, backticks
77
+ - `[url]` / `[img]` to Markdown links and images
78
+ - `[list]` / `[olist]` (nested) to `-` / `1.`
79
+ - `[quote]` (nested) to `>`
80
+ - `[hr][/hr]` to `---`
82
81
  - Steam-only tags such as `[spoiler]`, `[noparse]`, `[table]`, and `[u]` have no Markdown
83
82
  equivalent, so they pass through verbatim rather than being dropped
84
83
 
85
- ### Round-tripping
86
-
87
- `to_steam(to_markdown(steam))` returns the original markup, so a Steam -> Markdown -> Steam cycle
88
- is stable. The Markdown side is normalized rather than preserved byte for byte:
89
-
90
- - `####` and deeper collapse into `[h3]` on the way out, and come back as `###`
91
- - Image alt text is not carried by `[img]`, so it returns empty
92
- - A single-line fenced block returns as an inline code span
93
-
94
84
  ## Installation
95
85
 
96
86
  Install with pip or uv:
@@ -160,3 +150,23 @@ print(md_text)
160
150
  # - Fixed **crash** on startup
161
151
  # - [spoiler]Secret boss[/spoiler] added
162
152
  ```
153
+
154
+ ## Command line
155
+
156
+ The package installs a `steamify` console script alongside the library, and `python -m steamify` does
157
+ the same thing.
158
+
159
+ ```shell
160
+ steamify guide.md -o guide.txt # Markdown file to Steam file
161
+ steamify guide.md # Markdown file to stdout
162
+ steamify --to-markdown guide.txt # Steam file back to Markdown
163
+ cat guide.md | steamify # stdin to stdout
164
+ steamify -e latin-1 guide.md -o guide.txt # read and write as latin-1
165
+ ```
166
+
167
+ Conventions:
168
+
169
+ - `-` or an omitted argument means stdin; `-o -` or no `-o` means stdout.
170
+ - The default direction is Markdown to Steam. `--to-markdown` reverses it.
171
+ - `--encoding` applies to files and to stdin/stdout bytes alike, so pipes honor it too.
172
+ - Failures print a single `steamify: <message>` line on stderr and exit with code 1.