taganizer 0.1.0__tar.gz

taganizer-0.1.0/.flake8

@@ -0,0 +1,13 @@
+[flake8]
+max-line-length = 100
+# Ignore rules that conflict with black's formatting:
+#   E203 - whitespace before ':' (black formats slices this way)
+#   W503 - line break before binary operator (black's preferred style)
+extend-ignore = E203, W503
+exclude =
+    .git,
+    .venv,
+    dist,
+    build,
+    __pycache__,
+    *.egg-info

taganizer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          # Full history so setuptools-scm can derive the version from tags.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+          cache: pip
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check formatting
+        run: black --check .
+
+      - name: Lint
+        run: flake8 src tests
+
+      - name: Run tests
+        run: pytest tests

taganizer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC); no API token needed.
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          # Full history + tags so setuptools-scm derives the version from the tag.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

taganizer-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+tzr.db
+*.pyc
+src/taganizer.egg-info/
+dist/

taganizer-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: taganizer
+Version: 0.1.0
+Summary: A tag-based organization system
+Author-email: Hilko <hilkoc@users.noreply.github.com>
+Project-URL: Homepage, https://github.com/hilkoc/taganizer
+Project-URL: Repository, https://github.com/hilkoc/taganizer
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Requires-Dist: flake8>=7; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# Taganizer
+
+Taganizer is a tag-based item organizer. It stores items in SQLite, arranges them
+into a parent/child tag hierarchy, and lets you search by combining tags.
+
+It can be used as tool for agent memory.
+
+## Overview
+
+- Items are anything worth tracking: files, directories, URLs, snippets of text or other tags
+- Items are linked into a parent/child **tag hierarchy** (a directed acyclic graph); a
+  database trigger prevents cycles.
+- **Search** finds the intersection of tags, and supports the *union of intersections*:
+  `A B + C` means *(A and B) or C*.
+- Pure standard library, no dependencies. Requires Python 3.8+.
+
+## Installation
+
+The package defines a `tzr` entry point, so installing it puts a `tzr` command on your
+`PATH` — you can run `tzr <subcommand>` directly, with no `python -m taganizer.cli` prefix.
+Install from a checkout of the repository (use `.`), or once published, from PyPI (use
+`taganizer`). Verify with `tzr --version`.
+
+### Pipx
+
+Installs `tzr` into an isolated, globally available environment:
+
+```bash
+pipx install taganizer
+```
+
+### Pip
+
+Installs into the currently active Python environment:
+
+```bash
+pip install taganizer
+```
+
+
+## Usage
+
+By default the database lives at `~/.tzr.db`. Point at a different file with the global
+`--db PATH` flag (usable before or after the subcommand). See `tzr --version` and
+`tzr --help` for details.
+
+```bash
+# Create the database schema
+tzr init
+
+# Create some items
+tzr create tag python
+tzr create url https://example.com
+
+# Tag one item with another (child, parent)
+tzr tag https://example.com python   # -> "https://example.com tagged with python"
+
+# List items (optionally as a tree)
+tzr ls
+tzr ls --tree
+
+# Search: intersection of tags, or a union of intersections
+tzr search python
+tzr search python web + news        # (python and web) or news
+
+# Rename or delete items
+tzr rename python py
+tzr delete py
+
+# Export the database to a SQL dump (default: tzr_export.sql)
+tzr export
+tzr export my_dump.sql
+```
+
+### Commands
+
+| Command | Description |
+| --- | --- |
+| `tzr init` | Initialize the database schema. |
+| `tzr export [FILE]` | Export the database to an SQL dump file. |
+| `tzr ls` / `tzr list` | List all items (`--tree` shows the association tree). |
+| `tzr create <type> <name>` | Create a new item of the given type. |
+| `tzr rename <old> <new>` | Rename an item (its type is unchanged). |
+| `tzr delete <name>` | Delete an item (its tag links are removed; other items are unaffected). |
+| `tzr tag <child> <parent>` | Associate an item with a parent tag. |
+| `tzr search <query>...` | Search items by tag; `+` unions groups. |
+
+
+## Library usage
+
+Taganizer can also be used directly as a library. `ItemStore` owns a single database
+connection and works as a context manager:
+
+```python
+from taganizer import ItemStore, Item
+
+with ItemStore("my.db") as store:
+    store.initialize()                       # create schema (idempotent)
+    store.create_item(Item(-1, "TAG", "python"))
+    store.create_item(Item(-1, "URL", "https://example.com"))
+    store.associate("python", "https://example.com")
+
+    # search returns a tuple (map id ->Item, list of associations)
+    matches, _ = store.search([["python"]])
+    for item in matches.values():
+        print(item)
+# the connection is closed on exit
+```
+
+`SqlItemStore` is a drop-in subclass whose search resolves the union of intersections in
+a single SQL statement.
+
+## Development
+
+Set up an isolated virtual environment and install the project in editable mode so code
+changes take effect without reinstalling. Run `tzr <subcommand>` afterwards to exercise
+your changes.
+
+### Virtual environment
+
+Create and activate a virtual environment in the repository root:
+
+```bash
+python3 -m venv .venv          # create the environment
+source .venv/bin/activate      # activate it (Linux/macOS)
+# .venv\Scripts\activate       # activate it (Windows PowerShell/cmd)
+python -m pip install --upgrade pip
+```
+
+Then install the project. Include the `dev` extra to get the test and lint tools
+(`pytest`, `black`, `flake8`, `build`, `twine`):
+
+```bash
+pip install -e ".[dev]"        # editable install with dev tooling
+# pip install -e .             # or just the package, without dev tooling
+```
+
+Deactivate the environment when you're done with `deactivate`.
+
+### Pipx
+
+Alternatively, install `tzr` into an isolated, globally available environment:
+
+```bash
+pipx install --editable .
+```
+
+Run the test suite from the repository root (with the virtual environment activated):
+
+```bash
+pytest tests
+```
+
+## License
+
+Released under the MIT License.

taganizer-0.1.0/README.md

@@ -0,0 +1,156 @@
+# Taganizer
+
+Taganizer is a tag-based item organizer. It stores items in SQLite, arranges them
+into a parent/child tag hierarchy, and lets you search by combining tags.
+
+It can be used as tool for agent memory.
+
+## Overview
+
+- Items are anything worth tracking: files, directories, URLs, snippets of text or other tags
+- Items are linked into a parent/child **tag hierarchy** (a directed acyclic graph); a
+  database trigger prevents cycles.
+- **Search** finds the intersection of tags, and supports the *union of intersections*:
+  `A B + C` means *(A and B) or C*.
+- Pure standard library, no dependencies. Requires Python 3.8+.
+
+## Installation
+
+The package defines a `tzr` entry point, so installing it puts a `tzr` command on your
+`PATH` — you can run `tzr <subcommand>` directly, with no `python -m taganizer.cli` prefix.
+Install from a checkout of the repository (use `.`), or once published, from PyPI (use
+`taganizer`). Verify with `tzr --version`.
+
+### Pipx
+
+Installs `tzr` into an isolated, globally available environment:
+
+```bash
+pipx install taganizer
+```
+
+### Pip
+
+Installs into the currently active Python environment:
+
+```bash
+pip install taganizer
+```
+
+
+## Usage
+
+By default the database lives at `~/.tzr.db`. Point at a different file with the global
+`--db PATH` flag (usable before or after the subcommand). See `tzr --version` and
+`tzr --help` for details.
+
+```bash
+# Create the database schema
+tzr init
+
+# Create some items
+tzr create tag python
+tzr create url https://example.com
+
+# Tag one item with another (child, parent)
+tzr tag https://example.com python   # -> "https://example.com tagged with python"
+
+# List items (optionally as a tree)
+tzr ls
+tzr ls --tree
+
+# Search: intersection of tags, or a union of intersections
+tzr search python
+tzr search python web + news        # (python and web) or news
+
+# Rename or delete items
+tzr rename python py
+tzr delete py
+
+# Export the database to a SQL dump (default: tzr_export.sql)
+tzr export
+tzr export my_dump.sql
+```
+
+### Commands
+
+| Command | Description |
+| --- | --- |
+| `tzr init` | Initialize the database schema. |
+| `tzr export [FILE]` | Export the database to an SQL dump file. |
+| `tzr ls` / `tzr list` | List all items (`--tree` shows the association tree). |
+| `tzr create <type> <name>` | Create a new item of the given type. |
+| `tzr rename <old> <new>` | Rename an item (its type is unchanged). |
+| `tzr delete <name>` | Delete an item (its tag links are removed; other items are unaffected). |
+| `tzr tag <child> <parent>` | Associate an item with a parent tag. |
+| `tzr search <query>...` | Search items by tag; `+` unions groups. |
+
+
+## Library usage
+
+Taganizer can also be used directly as a library. `ItemStore` owns a single database
+connection and works as a context manager:
+
+```python
+from taganizer import ItemStore, Item
+
+with ItemStore("my.db") as store:
+    store.initialize()                       # create schema (idempotent)
+    store.create_item(Item(-1, "TAG", "python"))
+    store.create_item(Item(-1, "URL", "https://example.com"))
+    store.associate("python", "https://example.com")
+
+    # search returns a tuple (map id ->Item, list of associations)
+    matches, _ = store.search([["python"]])
+    for item in matches.values():
+        print(item)
+# the connection is closed on exit
+```
+
+`SqlItemStore` is a drop-in subclass whose search resolves the union of intersections in
+a single SQL statement.
+
+## Development
+
+Set up an isolated virtual environment and install the project in editable mode so code
+changes take effect without reinstalling. Run `tzr <subcommand>` afterwards to exercise
+your changes.
+
+### Virtual environment
+
+Create and activate a virtual environment in the repository root:
+
+```bash
+python3 -m venv .venv          # create the environment
+source .venv/bin/activate      # activate it (Linux/macOS)
+# .venv\Scripts\activate       # activate it (Windows PowerShell/cmd)
+python -m pip install --upgrade pip
+```
+
+Then install the project. Include the `dev` extra to get the test and lint tools
+(`pytest`, `black`, `flake8`, `build`, `twine`):
+
+```bash
+pip install -e ".[dev]"        # editable install with dev tooling
+# pip install -e .             # or just the package, without dev tooling
+```
+
+Deactivate the environment when you're done with `deactivate`.
+
+### Pipx
+
+Alternatively, install `tzr` into an isolated, globally available environment:
+
+```bash
+pipx install --editable .
+```
+
+Run the test suite from the repository root (with the virtual environment activated):
+
+```bash
+pytest tests
+```
+
+## License
+
+Released under the MIT License.

taganizer-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=80", "setuptools-scm[simple]>=9.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "taganizer"
+dynamic = ["version"]
+authors = [
+  {name = "Hilko", email = "hilkoc@users.noreply.github.com"},
+]
+description = "A tag-based organization system"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+# dependencies = ["sqlite3",]  # Built-in, no need to specify
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.5",
+    "black>=24",
+    "flake8>=7",
+    "build>=1",
+    "twine>=5",
+]
+
+[project.scripts]
+tzr = "taganizer.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hilkoc/taganizer"
+Repository = "https://github.com/hilkoc/taganizer"
+
+[tool.black]
+line-length = 100
+target-version = ["py314"]
+

taganizer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taganizer-0.1.0/src/taganizer/__init__.py

@@ -0,0 +1,6 @@
+"""Taganizer package."""
+
+from .item import Item, ItemError
+from .item_store import ItemStore, SqlItemStore
+
+__all__ = ["Item", "ItemError", "ItemStore", "SqlItemStore"]

taganizer-0.1.0/src/taganizer/cli.py

@@ -0,0 +1,232 @@
+#!/usr/bin/python3
+"""The main entry point for tzr."""
+
+import argparse
+import os
+import sys
+from importlib.metadata import version, PackageNotFoundError
+from .item import Item
+from . import item_store
+
+# Default database location: a hidden file in the user's home directory.
+DEFAULT_DB = "~/.tzr.db"
+
+try:
+    __version__ = version("taganizer")
+except PackageNotFoundError:  # not installed (e.g. run from a source checkout)
+    __version__ = "0.0.0"
+
+
+def db(db_path):
+    """Open and return an ItemStore for the given database path.
+
+    The returned store owns a single connection; use it as a context manager.
+    """
+    return item_store.ItemStore(os.path.expanduser(db_path))
+
+
+def output(*args, **kwargs):
+    print(*args, **kwargs)
+
+
+def show_item(item, level, indent):
+    temp = level * indent
+    output(temp, str(item), sep="")
+
+
+def init(store, args):
+    output("initializing database")
+    result = store.initialize()
+    output(result)
+
+
+def export(store, args):
+    output("Exporting database to %s" % args.dump_file)
+    with open(args.dump_file, "w") as f:
+        result = store.dump_db(f)
+    output(result)
+
+
+def build_tree(item_dict, pairs_list):
+    for pair in pairs_list:
+        p = item_dict[pair[0]]
+        c = item_dict[pair[1]]
+        p.add_child(c)
+
+
+def list_items(store, args):
+    item_dict = store.select_all()
+    if not args.tree:
+        for x in item_dict.values():
+            output(x)
+    else:
+        pairs_list = store.all_associations()
+        build_tree(item_dict, pairs_list)
+        for root in item_dict.values():
+            if root.parents is None:
+                root.traverse_children(show_item, "  ")
+
+
+def create(store, args):
+    item = Item(-1, args.type.upper(), args.name)
+    rowid = store.create_item(item)
+    output("created item with id: %i" % rowid)
+
+
+def rename(store, args):
+    rowcount = store.rename_item(args.old, args.new)
+    output("renamed %i item" % rowcount)
+
+
+def delete(store, args):
+    rowcount = store.delete_item(args.name)
+    output("deleted %i item" % rowcount)
+
+
+def add_association(store, args):
+    try:
+        store.associate(args.parent_name, args.child_name)
+    except ValueError as e:
+        output(
+            "tzr: cannot tag: %s. "
+            "Usage: tzr tag <child> <parent> — did you swap the arguments?" % e,
+            file=sys.stderr,
+        )
+        return 1
+    output("%s tagged with %s" % (args.child_name, args.parent_name))
+
+
+def split_groups(tokens):
+    """Split search tokens into groups on the '+' separator.
+
+    E.g. ['A', 'B', '+', 'C'] -> [['A', 'B'], ['C']], meaning (A ∩ B) ∪ (C).
+    """
+    groups, current = [], []
+    for tok in tokens:
+        if tok == "+":
+            if current:
+                groups.append(current)
+                current = []
+        else:
+            current.append(tok)
+    if current:
+        groups.append(current)
+    return groups
+
+
+def search(store, args):
+    groups = split_groups(args.query)
+    item_dict, pairs_list = store.search(groups)
+    build_tree(item_dict, pairs_list)
+    for root in item_dict.values():
+        if root.parents is None:
+            root.traverse_children(show_item, "  ")
+
+
+def main(main_args=None):
+    parser = argparse.ArgumentParser(
+        prog="tzr", description="Taganizer - a tag-based item organizer."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    # --db is accepted both before the subcommand (top-level, with the default) and after
+    # it (via the shared parent parser). SUPPRESS on the parent means it only overrides
+    # args.db when actually given, so it never clobbers a value passed before the subcommand.
+    parser.add_argument(
+        "--db",
+        default=DEFAULT_DB,
+        help=f"Path to the SQLite database file (default: {DEFAULT_DB}).",
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--db",
+        default=argparse.SUPPRESS,
+        help=f"Path to the SQLite database file (default: {DEFAULT_DB}).",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command_name",
+        title="subcommands",
+        description="valid subcommands",
+        help="sub-command help",
+    )
+    # the parser for the "init" command
+    parser_init = subparsers.add_parser(
+        "init", parents=[common], help="Initialize the database schema."
+    )
+    parser_init.set_defaults(func=init)
+    # the parser for the "export" command
+    parser_export = subparsers.add_parser(
+        "export", parents=[common], help="Export the database to an SQL dump file."
+    )
+    parser_export.add_argument(
+        "dump_file",
+        nargs="?",
+        default="tzr_export.sql",
+        help="File to write the SQL dump to (default: tzr_export.sql).",
+    )
+    parser_export.set_defaults(func=export)
+    # the parser for the "ls" command
+    parser_ls = subparsers.add_parser(
+        "ls", parents=[common], aliases=["list"], help="List all items."
+    )
+    parser_ls.add_argument(
+        "-t", "--tree", action="store_true", help="Show items as a tree of associations."
+    )
+    parser_ls.set_defaults(func=list_items)
+    # the parser for the "create" command
+    parser_create = subparsers.add_parser(
+        "create",
+        parents=[common],
+        aliases=["cr", "add"],
+        help="Create a new item of the given type.",
+    )
+    parser_create.add_argument(
+        "type", choices=["tag", "dir", "url", "txt", "cmd"], help="Item type."
+    )
+    parser_create.add_argument("name", help="Tag name, or URL/value of the item.")
+    parser_create.set_defaults(func=create)
+    # the parser for the "rename" command
+    parser_rename = subparsers.add_parser(
+        "rename", parents=[common], aliases=["mv"], help="Rename an item (its type is unchanged)."
+    )
+    parser_rename.add_argument("old", help="Current name or URL of the item.")
+    parser_rename.add_argument("new", help="New name or URL of the item.")
+    parser_rename.set_defaults(func=rename)
+    # the parser for the "delete" command
+    parser_delete = subparsers.add_parser(
+        "delete", parents=[common], aliases=["rm", "del"], help="Delete an item."
+    )
+    parser_delete.add_argument(
+        "name",
+        help="Delete the item with the given name and all its associations.",
+    )
+    parser_delete.set_defaults(func=delete)
+    # the parser for the "tag" command
+    parser_tag = subparsers.add_parser(
+        "tag", parents=[common], aliases=["label"], help="Associate an item with a parent tag."
+    )
+    parser_tag.add_argument("child_name", help="Item to be tagged (child).")
+    parser_tag.add_argument("parent_name", help="Parent tag to apply.")
+    parser_tag.set_defaults(func=add_association)
+    # the parser for the "search" command
+    parser_search = subparsers.add_parser(
+        "search", parents=[common], aliases=["s", "show", "select"], help="Search items by tag."
+    )
+    parser_search.add_argument(
+        "query",
+        nargs="+",
+        help="Tags to search for. Example: 'A B + C' means items tagged with (A and B) or C.",
+    )
+    parser_search.set_defaults(func=search)
+
+    args = parser.parse_args(main_args)
+
+    if hasattr(args, "func"):
+        with db(args.db) as store:
+            return args.func(store, args) or 0
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))