org-parser 0.23.5__tar.gz

org_parser-0.23.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kajetan Rzepecki <k@spartan.works>
+
+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.

org_parser-0.23.5/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: org-parser
+Version: 0.23.5
+Summary: A parser for Org Mode documents
+License: MIT
+License-File: LICENSE
+Keywords: parsing,tree-sitter,org,org-mode
+Author: Kajetan Rzepecki
+Author-email: k@spartan.works
+Maintainer: Kajetan Rzepecki
+Maintainer-email: k@spartan.works
+Requires-Python: >=3.12,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Dist: tree-sitter (>=0.25,<1.0)
+Requires-Dist: tree-sitter-org (>=0.23.6)
+Project-URL: Documentation, https://idorobots.github.io/org-parser/
+Project-URL: Homepage, https://github.com/Idorobots/org-parser
+Project-URL: Issue Tracker, https://github.com/Idorobots/org-parser/issues
+Project-URL: Repository, https://github.com/Idorobots/org-parser
+Project-URL: Releases, https://github.com/Idorobots/org-parser/releases
+Description-Content-Type: text/markdown
+
+# Overview
+
+This project implements a Python parser for Emacs Org-Mode files
+providing nice semantic nodes in a hierarchical document tree. It's
+based on [this Tree-Sitter
+grammar](https://github.com/Idorobots/tree-sitter-org).
+
+`org-parser` was created as an alternative to the wonderful, but
+admittedly incomplete and unmaintained
+[`orgparse`](https://github.com/karlicoss/orgparse/). The main
+improvements on top of `orgparse` are:
+
+- *Almost* complete feature set, including markup, blocks, tables and
+  more niche constructs such as Babel calls.
+- Fully mutable tree for easy edits that preserves original document
+  whitespace & formatting.
+- Better document error handling and reporting, useful for validation.
+
+[See the documentation here.](https://idorobots.github.io/org-parser/)
+
+# Installation
+
+``` bash
+pip install org-parser
+```
+
+# Features
+
+- Semantic nodes with all the expected attributes
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... #+TITLE: Document
+... #+AUTHOR: Idorobots
+... :PROPERTIES:
+... :name: value
+... :END:
+... An example document.
+... * Heading 1
+... ** Heading 2               :tag:
+... *** Heading 3
+... ''')
+>>> doc.title
+RichText('Document')
+>>> doc.body
+[BlankLine(), Paragraph(body=RichText('An example document.\n'))]
+>>> doc.body_text
+'\nAn example document.\n'
+>>> doc.properties["name"]
+RichText('value')
+>>> len(doc.all_headings)
+3
+>>> doc.all_headings[1].tags
+['tag']
+```
+
+- Structured traversal
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... * Heading 1
+... ** Heading 2
+... *** Heading 3
+... ''')
+>>> doc.children[0].title
+RichText('Heading 1')
+>>> doc.children[0].children[0].title
+RichText('Heading 2')
+>>> doc.children[0].children[0].parent.title == "Heading 1"
+True
+>>> doc.children[0].children[0].siblings
+[]
+```
+
+- Original source whitespace and formatting preserved by default
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... #+TITLE: Original formatting
+... * Heading 1
+...   Indented section
+...      remains indented 
+...    in-tree.  
+... ''')
+>>> print(str(doc.children[0]))
+* Heading 1
+  Indented section
+     remains indented 
+   in-tree.  
+
+>>> print(doc.render())
+
+#+TITLE: Original formatting
+* Heading 1
+  Indented section
+     remains indented 
+   in-tree.  
+```
+
+- Fully mutable tree allowing dynamic edits
+
+``` python
+>>> from org_parser import loads
+>>> from org_parser.element import Paragraph
+>>> doc = loads('''
+... #+TITLE: Document title
+... * Heading 1
+...   Body text.
+... ''')
+>>> doc.title
+RichText('Document title')
+>>> doc.title.text = "Another title"
+>>> doc[0].body = [Paragraph.from_source("New *and* improved!")]
+>>> doc[0].title.text = "Improved heading"
+>>> print(doc.render())
+#+TITLE: Another title
+
+* Improved heading
+New *and* improved!
+```
+
+- Org Table support
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... |Value|Double|
+... |1| |
+... |2| |
+... |3| |
+... ''')
+>>> for r in doc.body[1].rows[1:]:
+...   r[1].text = str(2 * int(r[0].text))
+...   
+>>> print(doc.render())
+
+| Value | Double |
+| 1     | 2      |
+| 2     | 4      |
+| 3     | 6      |
+```
+
+- Rich Text support
+
+``` python
+>>> from org_parser.text import RichText
+>>> text = RichText.from_source("Supports *org-mode* /markup/ and inline_{objects}: <2026-03-29>")
+>>> text
+RichText('Supports *org-mode* /markup/ and inline_{objects}: <2026-03-29>')
+>>> text.parts
+[PlainText(text='Supports '), Bold(body=[PlainText(text='org-mode')]), PlainText(text=' '), Italic(body=[PlainText(text='markup')]), PlainText(text=' and inline'), Subscript(body=[PlainText(text='objects')], form='{}'), PlainText(text=': '), Timestamp(is_active=True, start_year=2026, start_month=3, start_day=29), PlainText(text='')]
+```
+
+- Error recovery
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... * Heading
+... SCHEDULED: yesterday
+... ''')
+>>> doc[0].scheduled is None
+True
+>>> doc.errors
+[ParseError(start_point=Point(row=2, column=0), end_point=Point(row=2, column=20), text='SCHEDULED: yesterday')]
+```
+

org_parser-0.23.5/docs/index.md

@@ -0,0 +1,169 @@
+# Overview
+
+This project implements a Python parser for Emacs Org-Mode files
+providing nice semantic nodes in a hierarchical document tree. It's
+based on [this Tree-Sitter
+grammar](https://github.com/Idorobots/tree-sitter-org).
+
+`org-parser` was created as an alternative to the wonderful, but
+admittedly incomplete and unmaintained
+[`orgparse`](https://github.com/karlicoss/orgparse/). The main
+improvements on top of `orgparse` are:
+
+- *Almost* complete feature set, including markup, blocks, tables and
+  more niche constructs such as Babel calls.
+- Fully mutable tree for easy edits that preserves original document
+  whitespace & formatting.
+- Better document error handling and reporting, useful for validation.
+
+[See the documentation here.](https://idorobots.github.io/org-parser/)
+
+# Installation
+
+``` bash
+pip install org-parser
+```
+
+# Features
+
+- Semantic nodes with all the expected attributes
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... #+TITLE: Document
+... #+AUTHOR: Idorobots
+... :PROPERTIES:
+... :name: value
+... :END:
+... An example document.
+... * Heading 1
+... ** Heading 2               :tag:
+... *** Heading 3
+... ''')
+>>> doc.title
+RichText('Document')
+>>> doc.body
+[BlankLine(), Paragraph(body=RichText('An example document.\n'))]
+>>> doc.body_text
+'\nAn example document.\n'
+>>> doc.properties["name"]
+RichText('value')
+>>> len(doc.all_headings)
+3
+>>> doc.all_headings[1].tags
+['tag']
+```
+
+- Structured traversal
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... * Heading 1
+... ** Heading 2
+... *** Heading 3
+... ''')
+>>> doc.children[0].title
+RichText('Heading 1')
+>>> doc.children[0].children[0].title
+RichText('Heading 2')
+>>> doc.children[0].children[0].parent.title == "Heading 1"
+True
+>>> doc.children[0].children[0].siblings
+[]
+```
+
+- Original source whitespace and formatting preserved by default
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... #+TITLE: Original formatting
+... * Heading 1
+...   Indented section
+...      remains indented 
+...    in-tree.  
+... ''')
+>>> print(str(doc.children[0]))
+* Heading 1
+  Indented section
+     remains indented 
+   in-tree.  
+
+>>> print(doc.render())
+
+#+TITLE: Original formatting
+* Heading 1
+  Indented section
+     remains indented 
+   in-tree.  
+```
+
+- Fully mutable tree allowing dynamic edits
+
+``` python
+>>> from org_parser import loads
+>>> from org_parser.element import Paragraph
+>>> doc = loads('''
+... #+TITLE: Document title
+... * Heading 1
+...   Body text.
+... ''')
+>>> doc.title
+RichText('Document title')
+>>> doc.title.text = "Another title"
+>>> doc[0].body = [Paragraph.from_source("New *and* improved!")]
+>>> doc[0].title.text = "Improved heading"
+>>> print(doc.render())
+#+TITLE: Another title
+
+* Improved heading
+New *and* improved!
+```
+
+- Org Table support
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... |Value|Double|
+... |1| |
+... |2| |
+... |3| |
+... ''')
+>>> for r in doc.body[1].rows[1:]:
+...   r[1].text = str(2 * int(r[0].text))
+...   
+>>> print(doc.render())
+
+| Value | Double |
+| 1     | 2      |
+| 2     | 4      |
+| 3     | 6      |
+```
+
+- Rich Text support
+
+``` python
+>>> from org_parser.text import RichText
+>>> text = RichText.from_source("Supports *org-mode* /markup/ and inline_{objects}: <2026-03-29>")
+>>> text
+RichText('Supports *org-mode* /markup/ and inline_{objects}: <2026-03-29>')
+>>> text.parts
+[PlainText(text='Supports '), Bold(body=[PlainText(text='org-mode')]), PlainText(text=' '), Italic(body=[PlainText(text='markup')]), PlainText(text=' and inline'), Subscript(body=[PlainText(text='objects')], form='{}'), PlainText(text=': '), Timestamp(is_active=True, start_year=2026, start_month=3, start_day=29), PlainText(text='')]
+```
+
+- Error recovery
+
+``` python
+>>> from org_parser import loads
+>>> doc = loads('''
+... * Heading
+... SCHEDULED: yesterday
+... ''')
+>>> doc[0].scheduled is None
+True
+>>> doc.errors
+[ParseError(start_point=Point(row=2, column=0), end_point=Point(row=2, column=20), text='SCHEDULED: yesterday')]
+```

org_parser-0.23.5/pyproject.toml

@@ -0,0 +1,160 @@
+[tool.poetry]
+name = "org-parser"
+version = "0.23.5"
+description = "A parser for Org Mode documents"
+authors = ["Kajetan Rzepecki <k@spartan.works>"]
+maintainers = ["Kajetan Rzepecki <k@spartan.works>"]
+homepage = "https://github.com/Idorobots/org-parser"
+repository = "https://github.com/Idorobots/org-parser"
+documentation = "https://idorobots.github.io/org-parser/"
+keywords = ["parsing", "tree-sitter", "org", "org-mode"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Compilers",
+  "Topic :: Text Processing :: Linguistic",
+  "Typing :: Typed",
+]
+license = "MIT"
+readme = "docs/index.md"
+packages = [{ include = "org_parser", from = "src" }]
+
+[tool.poetry.urls]
+"Issue Tracker" = "https://github.com/Idorobots/org-parser/issues"
+"Releases" = "https://github.com/Idorobots/org-parser/releases"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+tree-sitter = ">=0.25,<1.0"
+tree-sitter-org = ">=0.23.6"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.11"
+ruff = "^0.8"
+taskipy = "^1.14.1"
+pytest = "^8.3"
+pytest-cov = "^6.0"
+pyright = "^1.1"
+mkdocs = "^1.6"
+mkdocs-section-index = "^0.3"
+mkdocs-autorefs = "^1.4"
+mkdocs-material = "^9.7.6"
+mkdocstrings = { version = "^0.30", extras = ["python"] }
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+# ---------------------------------------------------------------------------
+# taskipy — useful tasks
+# ---------------------------------------------------------------------------
+
+[tool.taskipy.tasks]
+test = "pytest --cov=src/ --cov-report=term-missing"
+lint = "ruff check src/ tests/"
+lint-fix = "ruff check --fix src/ tests/"
+format-check = "ruff format --check src/ tests/"
+format = "ruff format src/ tests/"
+type = "mypy src/ tests"
+docs-build = "mkdocs build --strict"
+docs-serve = "mkdocs serve"
+check = "task format-check && task lint && task type && task test"
+
+# ---------------------------------------------------------------------------
+# ruff — linting & formatting
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Docstring style: prefer D211 (no blank line before class docstring) and
+    # D212 (summary on first line); disable the conflicting alternatives.
+    "D203",   # one-blank-line-before-class (conflicts with D211)
+    "D213",   # multi-line-summary-second-line (conflicts with D212)
+    # Formatter compatibility and readability expectations in this codebase.
+    "COM812", # missing-trailing-comma (handled by formatter)
+    "ISC001", # single-line-implicit-string-concatenation (handled by formatter)
+    # Rules that are currently too noisy or conflict with project patterns.
+    "DTZ001", # call-datetime-without-tzinfo
+    "EM101",  # raw-string-in-exception
+    "EM102",  # f-string-in-exception
+    "PLR0913", # too-many-arguments
+    "PLR2004", # magic-value-comparison (too many false positives in tests)
+    "SLF001", # private-member-access
+    "TRY003", # raise-vanilla-args
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "D",      # docstrings not required in test files
+    "PT011",  # existing tests intentionally assert broad ValueError paths
+    "PT015",  # legacy assertion style retained in negative-path tests
+    "PT018",  # compound assertions retained for concise readability
+    "S101",   # assert is expected in tests
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["org_parser"]
+force-sort-within-sections = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+# ---------------------------------------------------------------------------
+# mypy — static type checking
+# ---------------------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+no_implicit_reexport = true
+show_error_codes = true
+pretty = true
+# Use the src layout
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+# tree-sitter ships incomplete type stubs; suppress import errors for it.
+module = ["tree_sitter", "tree_sitter.*"]
+ignore_missing_imports = true
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short --strict-markers -q"
+markers = ["integration: tests that require the compiled org.so shared library"]
+
+# ---------------------------------------------------------------------------
+# coverage
+# ---------------------------------------------------------------------------
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+omit = ["*/__init__.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 0

org_parser-0.23.5/src/org_parser/__init__.py

@@ -0,0 +1,116 @@
+"""org_parser — Python bindings for the tree-sitter org-mode parser.
+
+This package provides convenience helpers for loading and dumping Org Mode
+documents as [org_parser.document.Document][] instances.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from org_parser._lang import PARSER
+from org_parser.document import Document
+
+__all__ = ["Document", "dump", "dumps", "load", "loads"]
+
+
+def load(filename: str) -> Document:
+    """Load an Org Mode document from a file.
+
+    Args:
+        filename: Path to the Org Mode file.
+
+    Returns:
+        Parsed [org_parser.document.Document][] instance.
+
+    Example:
+    ```python
+    >>> from org_parser import load
+    >>> document = load('path/to/file.org')
+    >>> document.children[0].title_text
+    'Some heading'
+    ```
+    """
+    path = Path(filename)
+    source = path.read_bytes()
+    tree = PARSER.parse(source)
+    return Document.from_tree(tree, filename, source)
+
+
+def loads(source: str, filename: str | None = None) -> Document:
+    """Load an Org Mode document from a string.
+
+    Args:
+        source: Org Mode text to parse.
+        filename: Optional filename to assign to the parsed document.
+
+    Returns:
+        Parsed [org_parser.document.Document][] instance.
+
+    Example:
+    ```python
+    >>> from org_parser import loads
+    >>> document = loads("* TODO Heading 1")
+    >>> document.children[0].todo
+    'TODO'
+    ```
+    """
+    assigned_filename = filename if filename is not None else ""
+    source_bytes = source.encode()
+    tree = PARSER.parse(source_bytes)
+    return Document.from_tree(tree, assigned_filename, source_bytes)
+
+
+def dumps(document: Document) -> str:
+    """Return Org Mode text for a parsed document.
+
+    Produces the complete document text including all headings.  For clean
+    (unmodified) parse-backed documents the original source is returned
+    verbatim; for dirty documents every section is reconstructed from its
+    semantic fields.
+
+    Args:
+        document: Parsed document instance.
+
+    Returns:
+        Full Org Mode source text.
+
+    Example:
+    ```python
+    >>> from org_parser import dumps, loads
+    >>> document = loads("* TODO Heading 1")
+    >>> dumps(document).startswith("* TODO")
+    True
+    ```
+    """
+    return document.render()
+
+
+def dump(document: Document, filename: str | None = None) -> None:
+    """Write a parsed document to disk.
+
+    The output path is *filename* when provided; otherwise
+    [document.filename][org_parser.document.Document.filename].
+
+    Args:
+        document: Parsed document instance.
+        filename: Optional output path.
+
+    Raises:
+        ValueError: If neither *filename* nor ``document.filename`` is set.
+
+    Example:
+    ```python
+    >>> from pathlib import Path
+    >>> from org_parser import dump, loads
+    >>> document = loads("* TODO Heading 1")
+    >>> dump(document, 'path/to/file.org')
+    >>> out = Path('path/to/file.org')
+    >>> out.read_text().startswith("* TODO")
+    True
+    ```
+    """
+    target = filename if filename is not None else document.filename
+    if target == "":
+        raise ValueError("No output filename provided")
+    Path(target).write_text(dumps(document))