{"id":34054957,"url":"https://github.com/thinmanj/logseq-python-library","last_synced_at":"2026-04-01T20:21:16.694Z","repository":{"id":318258389,"uuid":"1070521247","full_name":"thinmanj/logseq-python-library","owner":"thinmanj","description":"🐍 Comprehensive Python library for Logseq knowledge graph interaction. Read, query, and modify Logseq data programmatically with advanced search capabilities.","archived":false,"fork":false,"pushed_at":"2025-11-05T03:19:05.000Z","size":633,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-03T21:53:12.574Z","etag":null,"topics":["automation","data-export","knowledge-graph","logseq","markdown","note-taking","python","query-builder"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thinmanj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-06T04:01:10.000Z","updated_at":"2025-11-24T08:19:59.000Z","dependencies_parsed_at":"2025-10-06T06:21:58.327Z","dependency_job_id":"2ac03767-0808-4e64-a7da-2da79b7bcb95","html_url":"https://github.com/thinmanj/logseq-python-library","commit_stats":null,"previous_names":["thinmanj/logseq-python-library"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/thinmanj/logseq-python-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinmanj%2Flogseq-python-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinmanj%2Flogseq-python-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinmanj%2Flogseq-python-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinmanj%2Flogseq-python-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thinmanj","download_url":"https://codeload.github.com/thinmanj/logseq-python-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thinmanj%2Flogseq-python-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31019071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T03:51:26.850Z","status":"ssl_error","status_checked_at":"2026-03-27T03:51:09.693Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","data-export","knowledge-graph","logseq","markdown","note-taking","python","query-builder"],"created_at":"2025-12-14T02:34:15.961Z","updated_at":"2026-03-27T04:29:10.512Z","avatar_url":"https://github.com/thinmanj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐍 Logseq Python Library\n\n**The most comprehensive Python library for Logseq knowledge graph interaction**\n\nTransform your Logseq workflow with programmatic access to every major feature. From basic note-taking to advanced task management, academic research, and knowledge graph analytics - this library supports it all.\n\n[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/thinmanj/logseq-python-library/blob/main/LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/thinmanj/logseq-python-library.svg)](https://github.com/thinmanj/logseq-python-library/stargazers)\n\n## ✨ **Comprehensive Feature Support**\n\n### 🎯 **Task Management \u0026 Workflows**\n- ✅ **Complete Task System**: TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED, DELEGATED, IN-PROGRESS\n- ✅ **Priority Levels**: A, B, C with full parsing and filtering\n- ✅ **Scheduling**: SCHEDULED dates with time and repeaters (+1w, +3d)\n- ✅ **Deadlines**: DEADLINE tracking with overdue detection\n- ✅ **Workflow Analytics**: Completion rates, productivity metrics\n\n### 📝 **Advanced Content Types**\n- ✅ **Code Blocks**: Language detection, syntax highlighting support\n- ✅ **Mathematics**: LaTeX/Math parsing ($$math$$, \\\\(inline\\\\))\n- ✅ **Queries**: {{query}} and #+begin_query support\n- ✅ **Headings**: H1-H6 hierarchical structure\n- ✅ **References**: ((block-id)) linking and {{embed}} support\n- ✅ **Properties**: Advanced property parsing and querying\n\n### 🗂️ **Organization \u0026 Structure**\n- ✅ **Namespaces**: project/backend hierarchical organization\n- ✅ **Templates**: Template variables {{variable}} parsing\n- ✅ **Aliases**: Page alias system with [[link]] support\n- ✅ **Whiteboards**: .whiteboard file detection\n- ✅ **Hierarchies**: Parent/child page relationships\n\n### 📊 **Knowledge Graph Analytics**\n- ✅ **Graph Insights**: Connection analysis, relationship mapping\n- ✅ **Content Statistics**: Block type distribution, tag usage\n- ✅ **Productivity Metrics**: Task completion trends\n- ✅ **Workflow Summaries**: Advanced task analytics\n\n### 🔍 **Powerful Query System**\n- ✅ **25+ Query Methods**: Task states, priorities, content types\n- ✅ **Date Filtering**: Scheduled, deadline, creation date queries\n- ✅ **Content Filtering**: Code language, math content, headings\n- ✅ **Relationship Queries**: Block references, embeds, backlinks\n- ✅ **Advanced Combinations**: Chain multiple filters fluently\n\n## Installation\n\n```bash\npip install logseq-py\n```\n\nOr for development:\n\n```bash\ngit clone https://github.com/yourusername/logseq-python.git\ncd logseq-python\npip install -e .\n```\n\n## 🚀 **Quick Start**\n\n### Basic Setup\n```python\nfrom logseq_py import LogseqClient, TaskState, Priority\n\n# Initialize client with your Logseq graph directory\nclient = LogseqClient(\"/path/to/your/logseq/graph\")\ngraph = client.load_graph()\n```\n\n### 📋 **Task Management**\n```python\n# Find all high-priority tasks\nurgent_tasks = client.query().blocks().has_priority(Priority.A).execute()\n\n# Get overdue tasks\nfrom datetime import date\noverdue = client.query().blocks().has_deadline().custom_filter(\n    lambda block: block.deadline.date \u003c date.today()\n).execute()\n\n# Find completed tasks\ncompleted = client.query().blocks().has_task_state(TaskState.DONE).execute()\n\n# Get workflow summary\nworkflow = client.graph.get_workflow_summary()\nprint(f\"Completion rate: {workflow['completed_tasks']}/{workflow['total_tasks']}\")\n```\n\n### 💻 **Code \u0026 Content Analysis**\n```python\n# Find all Python code blocks\npython_code = client.query().blocks().is_code_block(language=\"python\").execute()\n\n# Get math/LaTeX content\nmath_blocks = client.query().blocks().has_math_content().execute()\n\n# Find all headings\nheadings = client.query().blocks().is_heading().execute()\n\n# Get blocks with references\nlinked_blocks = client.query().blocks().has_block_references().execute()\n```\n\n### 📊 **Advanced Analytics**\n```python\n# Get comprehensive graph insights\ninsights = client.graph.get_graph_insights()\n\n# Analyze namespaces\nfor namespace in client.graph.get_all_namespaces():\n    pages = client.graph.get_pages_by_namespace(namespace)\n    print(f\"{namespace}/: {len(pages)} pages\")\n\n# Find most connected pages\nfor page_name, connections in insights['most_connected_pages'][:5]:\n    print(f\"{page_name}: {connections} backlinks\")\n```\n\n### ✍️ **Content Creation**\n```python\n# Add journal entry with task\nclient.add_journal_entry(\"TODO Review project documentation #urgent\")\n\n# Create a structured page\ncontent = \"\"\"# Project Planning\n- TODO Set up initial framework [#A]\n  SCHEDULED: \u003c2024-01-15 Mon\u003e\n- Code review checklist\n  - [ ] Security audit\n  - [ ] Performance testing\"\"\"\n\nclient.create_page(\"Project Alpha\", content)\n```\n\n## 🎯 **Real-World Use Cases**\n\n### 📈 **Project Management**\n- Track tasks across multiple projects with priorities and deadlines\n- Generate productivity reports and completion metrics\n- Automate workflow status updates and notifications\n- Analyze team performance and bottlenecks\n\n### 🔬 **Academic Research**\n- Parse and analyze LaTeX mathematical content\n- Extract and organize research notes with citations\n- Track paper progress and review status\n- Generate bibliographies and reference networks\n\n### 💻 **Software Development**\n- Document code examples with syntax highlighting\n- Track bugs and feature requests with priority levels\n- Organize documentation by namespace (frontend/backend)\n- Generate code statistics and language usage reports\n\n### 📚 **Knowledge Management**\n- Build comprehensive knowledge graphs with relationships\n- Track learning progress with spaced repetition\n- Organize information hierarchically with namespaces\n- Generate insights about information consumption patterns\n\n### 🎨 **Creative Work**\n- Organize creative projects with visual whiteboards\n- Track inspiration and reference materials\n- Manage creative workflows with custom task states\n- Analyze creative output patterns and productivity\n\n## 🛠️ **Advanced Examples**\n\n### Task Automation\n```python\n# Find all overdue high-priority tasks and generate a report\nfrom datetime import date, timedelta\n\noverdue_urgent = (client.query()\n    .blocks()\n    .is_task()\n    .has_priority(Priority.A)\n    .has_deadline()\n    .custom_filter(lambda b: b.deadline.date \u003c date.today())\n    .execute())\n\nfor task in overdue_urgent:\n    days_overdue = (date.today() - task.deadline.date).days\n    print(f\"⚠️ OVERDUE {days_overdue} days: {task.content}\")\n```\n\n### Content Analysis\n```python\n# Analyze your coding activity across languages\ncode_stats = {}\nfor block in client.query().blocks().is_code_block().execute():\n    lang = block.code_language or 'unknown'\n    code_stats[lang] = code_stats.get(lang, 0) + 1\n\nprint(\"📊 Code block distribution:\")\nfor lang, count in sorted(code_stats.items(), key=lambda x: x[1], reverse=True):\n    print(f\"  {lang}: {count} blocks\")\n```\n\n### Knowledge Graph Analysis\n```python\n# Find your most referenced pages (knowledge hubs)\npage_refs = {}\nfor block in client.query().blocks().has_block_references().execute():\n    for ref in block.referenced_blocks:\n        page_refs[ref] = page_refs.get(ref, 0) + 1\n\nprint(\"🔗 Most referenced content:\")\nfor ref, count in sorted(page_refs.items(), key=lambda x: x[1], reverse=True)[:10]:\n    print(f\"  {ref}: {count} references\")\n```\n\n## 🚀 **Warp Terminal Integration**\n\n**NEW!** Seamlessly integrate logseq-python into your Warp terminal workflows:\n\n- ✅ **7 Pre-built Workflows**: Task summaries, graph insights, content extraction, code stats\n- ✅ **One-Command Access**: `Cmd+P` → type \"Logseq\" to run any workflow\n- ✅ **Customizable**: Easy YAML configuration for your own workflows\n- ✅ **Powerful Automation**: Daily routines, batch processing, scheduled tasks\n\n### Quick Setup\n```bash\n# Copy workflow file to your Logseq graph\ncd /path/to/your/logseq/graph\nmkdir -p .warp/workflows\ncp /path/to/logseq-python/.warp/workflows/logseq-automation.yaml .warp/workflows/\n\n# Use in Warp: Cmd+P → \"Logseq: Daily Task Summary\"\n```\n\n📚 **[Full Warp Integration Guide](WARP_INTEGRATION.md)**\n\n---\n\n## 📖 **Documentation**\n\n- 📘 [Complete API Reference](docs/api.md) - Comprehensive API documentation\n- 🚀 [Warp Integration Guide](WARP_INTEGRATION.md) - **NEW!** Terminal workflow automation\n- 🎯 [Basic Usage Examples](examples/basic_usage.py) - Get started quickly\n- 🔍 [Advanced Queries](examples/advanced_queries.py) - Complex search examples\n- 🎨 [Advanced Features](examples/advanced_logseq_features.py) - All new features showcase\n- 📤 [Data Export/Import](examples/data_export_import.py) - Backup and analysis\n- 🧪 [Test Suite](tests/) - Comprehensive testing examples\n\n## Requirements\n\n- Python 3.8+\n- Logseq graph (local directory)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nThe MIT License is a permissive license that allows for commercial use, modification, distribution, and private use, with the only requirement being that the license and copyright notice must be included with any substantial portions of the software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinmanj%2Flogseq-python-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthinmanj%2Flogseq-python-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinmanj%2Flogseq-python-library/lists"}