beancount-ast 0.0.1a0__tar.gz → 0.0.1a2__tar.gz

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/.github/workflows/tests.yml

@@ -43,6 +43,9 @@ jobs:
           - windows-11-arm
           - ubuntu-24.04
           - ubuntu-24.04-arm
+        exclude:
+          - platform: windows-11-arm
+            python: '3.10'
     steps:
       - uses: actions/checkout@v6
 

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/.gitignore

@@ -8,6 +8,7 @@
 *~
 .cache
 .idea
+.vscode/
 .noseids
 .pytest_cache/*
 TAGS
@@ -25,3 +26,4 @@ experiments/v3/arrow/*.arrow
 .aider*
 .env
 target
+uv.lock

beancount_ast-0.0.1a2/AGENTS.md

@@ -0,0 +1,47 @@
+# Copilot instructions (beancount-ast)
+
+## Project overview
+- This repo provides Python bindings (PyO3) for the Rust `beancount-parser` directive AST.
+- The Python API intentionally exposes the **parser AST** (directives + spans + raw tokens), not Beancount’s semantic `beancount.core` model.
+
+## Key layout
+- `src/lib.rs`: the PyO3 module `beancount_ast._ast`.
+  - Registers all exposed Python classes in `#[pymodule(name = "_ast")]`.
+  - Converts Rust parser nodes (`beancount_parser::ast::*`) into `Py*` structs.
+  - Public Python entrypoints are `parse_string` and `parse_file`.
+- `py-src/beancount_ast/__init__.py`: re-exports symbols from `beancount_ast._ast`.
+- `py-src/beancount_ast/_ast.pyi`: stubs of `src/lib.rs`, when you change any interface, you should also update it.
+- `tests/test_parse_snapshots.py`: snapshot-style API tests using `pytest` + `syrupy`.
+
+## Workflows (local + CI-aligned)
+- Python deps / test env are managed with `uv` (see `.github/workflows/tests.yml`).
+  - Setup: `uv sync --dev --no-install-project`
+  - Run tests: `uv run pytest`
+- Rust checks mirror CI (`.github/workflows/ci.yml`):
+  - Format: `cargo fmt --all -- --check`
+  - Lint: `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+
+## Conventions to follow when changing Rust bindings
+- Avoid `unwrap()` / `expect()`; the crate denies them (`src/lib.rs` has `#![deny(clippy::unwrap_used, clippy::expect_used)]`).
+- Python-facing data structures are thin, mostly immutable “record” types:
+  - Define a `Py*` struct with `#[pyclass(..., get_all)]` and `pyderive` derives (`PyNew`, `PyRepr`, `PyStr`, and sometimes `PyEq`).
+  - If the type should appear in stubs, add `#[cfg_attr(feature = "stub-gen", ...gen_stub_pyclass)]`.
+- When adding a new directive/type:
+  1) Add the `Py*` struct.
+  2) Register it in the `_ast` module init.
+  3) Extend the conversion layer (e.g. `directive_to_py(...)`).
+  4) Update the `Directive` type alias used for stubs (see the `stub-gen` block at the end of `src/lib.rs`).
+
+## Stub generation
+- The stub generator binary is `src/bin/stub_gen.rs` and is only available with the `stub-gen` feature.
+- Typical command:
+  - `cargo run --bin stub_gen --features stub-gen`
+- The generated output updates `py-src/beancount_ast/_ast.pyi`.
+
+## Formatting / linting
+- Non-code config formatting uses `dprint` (see `dprint.json`) and is enforced via pre-commit.
+- Python formatting/linting uses `ruff` + `black` (see `.pre-commit-config.yaml`).
+
+## Release notes (when relevant)
+- CI builds wheels via `maturin` (see `.github/workflows/_build_wheels.yaml`).
+- Tags `v*` publish to PyPI (see `.github/workflows/release.yaml`).

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/Cargo.lock

@@ -648,6 +648,7 @@ version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b455933107de8642b4487ed26d912c2d899dec6114884214a0b3bb3be9261ea6"
 dependencies = [
+ "python3-dll-a",
  "target-lexicon",
 ]
 
@@ -721,6 +722,15 @@ dependencies = [
  "syn 2.0.114",
 ]
 
+[[package]]
+name = "python3-dll-a"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d381ef313ae70b4da5f95f8a4de773c6aa5cd28f73adec4b4a31df70b66780d8"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.44"

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/Cargo.toml

@@ -20,7 +20,7 @@ required-features = ["stub-gen"]
 [dependencies]
 beancount-parser = { git = "https://github.com/trim21/beancount.git", rev = "8b4e3311258194fe3127862dd4132028e97cc01d" }
 pyderive = "0.9.2"
-pyo3 = { version = "0.27.2", features = ["abi3-py310", "multiple-pymethods"] }
+pyo3 = { version = "0.27.2", features = ["abi3-py310", "multiple-pymethods", "generate-import-lib"] }
 pyo3-stub-gen = { git = "https://github.com/Jij-Inc/pyo3-stub-gen", rev = "42dfdd813900015f6dbb7946f9a5878ceadb3fa3", optional = true }
 pyo3-stub-gen-derive = { git = "https://github.com/Jij-Inc/pyo3-stub-gen", rev = "42dfdd813900015f6dbb7946f9a5878ceadb3fa3", optional = true }
 

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beancount_ast
-Version: 0.0.1a0
+Version: 0.0.1a2
 Summary: Parse Beancount content into AST
 Home-Page: https://github.com/trim21/beancount-ast
 Requires-Python: >=3.10

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/py-src/beancount_ast/__init__.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING
+
 from ._ast import Amount
 from ._ast import Balance
 from ._ast import Close
@@ -33,11 +35,14 @@ from ._ast import SpannedPriceOperator
 from ._ast import SpannedStr
 from ._ast import Tag
 from ._ast import Transaction
-from ._ast import TransactionExtra
 from ._ast import parse_file
 from ._ast import parse_string
 
+if TYPE_CHECKING:
+    from ._ast import Directive
+
 __all__ = [
+    "Directive",
     "Amount",
     "Balance",
     "Close",
@@ -73,7 +78,6 @@ __all__ = [
     "SpannedStr",
     "Tag",
     "Transaction",
-    "TransactionExtra",
     "parse_file",
     "parse_string",
 ]

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/py-src/beancount_ast/_ast.pyi

@@ -18,6 +18,7 @@ __all__ = [
     "Directive",
     "Document",
     "Event",
+    "File",
     "Headline",
     "Include",
     "KeyValue",
@@ -42,7 +43,6 @@ __all__ = [
     "SpannedStr",
     "Tag",
     "Transaction",
-    "TransactionExtra",
     "parse_file",
     "parse_string",
 ]
@@ -70,6 +70,15 @@ Directive: TypeAlias = (
     | Headline
 )
 
+@typing.final
+class File:
+    @property
+    def filename(self) -> builtins.str: ...
+    @property
+    def content(self) -> builtins.str: ...
+    @property
+    def directives(self) -> builtins.list[Directive]: ...
+
 @typing.final
 class Amount:
     @property
@@ -78,6 +87,7 @@ class Amount:
     def number(self) -> NumberExpr: ...
     @property
     def currency(self) -> typing.Optional[SpannedStr]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Balance:
@@ -86,6 +96,8 @@ class Balance:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -97,6 +109,7 @@ class Balance:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Close:
@@ -105,6 +118,8 @@ class Close:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -112,6 +127,7 @@ class Close:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Comment:
@@ -120,7 +136,10 @@ class Comment:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def text(self) -> SpannedStr: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Commodity:
@@ -129,6 +148,8 @@ class Commodity:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def currency(self) -> SpannedStr: ...
@@ -136,6 +157,7 @@ class Commodity:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class CostAmount:
@@ -160,6 +182,7 @@ class CostSpec:
     def merge(self) -> typing.Optional[SpannedBool]: ...
     @property
     def is_total(self) -> SpannedBool: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Custom:
@@ -168,6 +191,8 @@ class Custom:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def name(self) -> SpannedStr: ...
@@ -177,6 +202,7 @@ class Custom:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class CustomValue:
@@ -188,6 +214,7 @@ class CustomValue:
     def number(self) -> typing.Optional[NumberExpr]: ...
     @property
     def amount(self) -> typing.Optional[Amount]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Document:
@@ -196,6 +223,8 @@ class Document:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -211,6 +240,7 @@ class Document:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Event:
@@ -219,6 +249,8 @@ class Event:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def event_type(self) -> SpannedStr: ...
@@ -228,6 +260,7 @@ class Event:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Headline:
@@ -236,7 +269,10 @@ class Headline:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def text(self) -> SpannedStr: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Include:
@@ -245,7 +281,10 @@ class Include:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def filename(self) -> SpannedStr: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class KeyValue:
@@ -254,9 +293,12 @@ class KeyValue:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def key(self) -> SpannedStr: ...
     @property
     def value(self) -> typing.Optional[SpannedKeyValueValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class KeyValueValue:
@@ -283,6 +325,8 @@ class Note:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -292,6 +336,7 @@ class Note:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class NumberExpr:
@@ -300,6 +345,8 @@ class NumberExpr:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def literal(self) -> typing.Optional[SpannedStr]: ...
     @property
     def left(self) -> typing.Optional[NumberExpr]: ...
@@ -307,6 +354,7 @@ class NumberExpr:
     def op(self) -> typing.Optional[SpannedBinaryOp]: ...
     @property
     def right(self) -> typing.Optional[NumberExpr]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Open:
@@ -315,6 +363,8 @@ class Open:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -326,6 +376,7 @@ class Open:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Option:
@@ -334,9 +385,12 @@ class Option:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def key(self) -> SpannedStr: ...
     @property
     def value(self) -> SpannedStr: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Pad:
@@ -345,6 +399,8 @@ class Pad:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -354,6 +410,7 @@ class Pad:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Plugin:
@@ -362,9 +419,12 @@ class Plugin:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def name(self) -> SpannedStr: ...
     @property
     def config(self) -> typing.Optional[SpannedStr]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class PopMeta:
@@ -373,7 +433,10 @@ class PopMeta:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def key(self) -> SpannedStr: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Posting:
@@ -382,6 +445,8 @@ class Posting:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def opt_flag(self) -> typing.Optional[SpannedStr]: ...
     @property
     def account(self) -> SpannedStr: ...
@@ -397,6 +462,7 @@ class Posting:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Price:
@@ -405,6 +471,8 @@ class Price:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def currency(self) -> SpannedStr: ...
@@ -414,6 +482,7 @@ class Price:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class PushMeta:
@@ -422,9 +491,12 @@ class PushMeta:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def key(self) -> SpannedStr: ...
     @property
     def value(self) -> typing.Optional[SpannedKeyValueValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Query:
@@ -433,6 +505,8 @@ class Query:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def name(self) -> SpannedStr: ...
@@ -442,6 +516,7 @@ class Query:
     def comment(self) -> typing.Optional[SpannedStr]: ...
     @property
     def key_values(self) -> builtins.list[KeyValue]: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Span:
@@ -455,35 +530,50 @@ class SpannedBinaryOp:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def content(self) -> builtins.str: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class SpannedBool:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def content(self) -> builtins.bool: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class SpannedKeyValueValue:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def content(self) -> KeyValueValue: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class SpannedPriceOperator:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def content(self) -> builtins.str: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class SpannedStr:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def content(self) -> builtins.str: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Tag:
@@ -492,9 +582,12 @@ class Tag:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def tag(self) -> SpannedStr: ...
     @property
     def action(self) -> builtins.str: ...
+    def dump(self) -> builtins.str: ...
 
 @typing.final
 class Transaction:
@@ -503,6 +596,8 @@ class Transaction:
     @property
     def span(self) -> Span: ...
     @property
+    def file(self) -> File: ...
+    @property
     def date(self) -> SpannedStr: ...
     @property
     def txn(self) -> typing.Optional[SpannedStr]: ...
@@ -518,11 +613,6 @@ class Transaction:
     def links(self) -> builtins.list[SpannedStr]: ...
     @property
     def comment(self) -> typing.Optional[SpannedStr]: ...
-    @property
-    def extra(self) -> TransactionExtra: ...
-
-@typing.final
-class TransactionExtra:
     @property
     def tags_links_lines(self) -> builtins.list[SpannedStr]: ...
     @property
@@ -531,8 +621,9 @@ class TransactionExtra:
     def key_values(self) -> builtins.list[KeyValue]: ...
     @property
     def postings(self) -> builtins.list[Posting]: ...
+    def dump(self) -> builtins.str: ...
 
-def parse_file(filename: builtins.str) -> builtins.list[Directive]: ...
+def parse_file(filename: builtins.str) -> File: ...
 def parse_string(
     content: builtins.str, filename: builtins.str = "<string>"
-) -> builtins.list[Directive]: ...
+) -> File: ...

{beancount_ast-0.0.1a0 → beancount_ast-0.0.1a2}/pyproject.toml

@@ -7,7 +7,7 @@ name = "beancount_ast"
 description = "Parse Beancount content into AST"
 readme = "README.md"
 requires-python = ">=3.10"
-version = '0.0.1.a0'
+version = '0.0.1a2'
 dependencies = []
 
 [tool.pytest.ini_options]