logseq-md 0.1.0__py3-none-any.whl

logseq_md/__init__.py

@@ -0,0 +1,21 @@
+"""Read and write file-based Logseq markdown graphs.
+
+A Logseq file graph is a directory of markdown: `pages/` for topics, `journals/`
+for dates, one block per bullet, nested by indentation. This package reads that
+shape and writes back into it without reformatting the parts it did not touch.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+#: Resolved from the installed distribution rather than written here, so there is
+#: one version in the repository and the release job owns it. A source checkout
+#: that was never installed has no distribution metadata, and reports that rather
+#: than guessing.
+try:  # pragma: no cover - the except branch needs an uninstalled checkout
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("logseq-md")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"

logseq_md/__main__.py

@@ -0,0 +1,8 @@
+"""Allow `python -m logseq_md` as well as the console script."""
+
+from __future__ import annotations
+
+from logseq_md.cli import run
+
+if __name__ == "__main__":
+    run()

logseq_md/cli.py

@@ -0,0 +1,51 @@
+"""The command line entry point.
+
+Nothing reads a graph yet. What is here is the parser, the version flag and the
+exit convention, which is what the packaging, the entry point and the smoke test
+in CI need in order to be checked before there is anything to check them on.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from logseq_md import __version__
+
+#: Exit codes. `2` is argparse's own code for a usage error and is not reused
+#: here for anything else, so a caller can tell "you asked wrongly" from "the
+#: graph said no".
+OK = 0
+FAILED = 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argument parser, built separately so a test can inspect it."""
+    parser = argparse.ArgumentParser(
+        prog="logseq-md",
+        description="Read and write file-based Logseq markdown graphs.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command and return its exit code.
+
+    Returning rather than exiting keeps the whole command testable in-process;
+    `run` is the thin wrapper the console script points at.
+    """
+    parser = build_parser()
+    parser.parse_args(argv)
+    parser.print_help()
+    return OK
+
+
+def run() -> None:
+    """Console script entry point."""
+    sys.exit(main())

logseq_md-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: logseq-md
+Version: 0.1.0
+Summary: Read and write file-based Logseq markdown graphs from the command line
+Project-URL: Homepage, https://github.com/ftschindler/logseq-md
+Project-URL: Source, https://github.com/ftschindler/logseq-md
+Project-URL: Issues, https://github.com/ftschindler/logseq-md/issues
+Author: Felix Schindler
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,logseq,markdown,notes,outliner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# logseq-md
+
+Read and write file-based Logseq markdown graphs from the command line.
+
+A Logseq file graph is a directory of markdown: `pages/` for topics, `journals/` for dates, one
+block per bullet, nested by indentation, with `property:: value` lines, `[[page]]` links and
+`((uuid))` block references. Ordinary tools read it well enough. Writing back into it is where
+they go wrong.
+
+```sh
+uvx logseq-md --help
+```
+
+That needs no install beyond [uv](https://docs.astral.sh/uv/).
+
+**Pre-alpha.** The packaging, the entry point and the guard suite are in place. Nothing reads a
+graph yet.
+
+## What this is for
+
+Agents and scripts that work against a graph the owner also edits by hand, in the app, on more
+than one machine.
+
+The constraint that shapes everything here: **a write changes the bytes it meant to change and
+no others.** Every library in this space parses a page into a tree and serialises the tree back
+over the file, which is correct in the sense that Logseq still reads it, and wrong in three
+ways that matter.
+
+- A one-line status append arrives as a thousand-line diff, so nobody reviews it.
+- A graph is usually not a git repository, so a reflow is damage with no way back.
+- A graph that syncs between devices gets conflicts, and a conflict between two files that each
+  changed one line is a mechanical merge, while a conflict where one side reflowed everything
+  cannot be merged by anything, including a person.
+
+So the write path here splices lines into the file it was given. The round-trip test is the
+acceptance criterion rather than a nicety: parse every file in a graph, write it back unchanged,
+and assert the bytes are identical.
+
+## What it will not do
+
+It knows about blocks, markers, properties, references, pages, journals and ids. It knows
+nothing about what you use them for. There is no notion of a task queue, no integration with any
+forge, no opinion about which of your graphs is private, and no daemon resolving sync conflicts.
+
+The test of that boundary: every verb and flag is expressible in Logseq's own vocabulary. A flag
+that needs a word Logseq does not have belongs in whatever is calling this, not here.
+
+## Development
+
+```sh
+make bootstrap   # install the pre-commit hooks into this clone
+make test        # run the suite
+make check       # run the full guard suite over every file
+```
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the system requirements.
+
+## Licence
+
+[MIT](LICENSE).

logseq_md-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+logseq_md/__init__.py,sha256=VxWAMuCSP1NKvAHLthpKq6WEIPO0-GET3Q89YhSFenQ,887
+logseq_md/__main__.py,sha256=1WBom-HwSw32_q7LRYvEByKypNtzbol9eT3gdQ1h2Xw,170
+logseq_md/cli.py,sha256=pUmqpEKibSOk3C2OrlrFr3sfbD4ws-WacDYdMehj7MI,1436
+logseq_md-0.1.0.dist-info/METADATA,sha256=mIZs40ukkZvYUyWW8lO2Luq2gqqQ4WZyplGkC149mx0,3456
+logseq_md-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+logseq_md-0.1.0.dist-info/entry_points.txt,sha256=N3sfgVSFJmrXiVnp2fWkr3nxZZRgv7NnhZNtEUugDHc,48
+logseq_md-0.1.0.dist-info/licenses/LICENSE,sha256=45jm7nlf5VUNKHLwv_-x2ouCadL8HXXC5BVs6Pw_NsM,1079
+logseq_md-0.1.0.dist-info/RECORD,,

logseq_md-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

logseq_md-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+logseq-md = logseq_md.cli:run

logseq_md-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 logseq-md contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.