{"id":32520890,"url":"https://github.com/tks18/xl-pq-handler","last_synced_at":"2026-01-20T17:05:18.822Z","repository":{"id":320587588,"uuid":"1082519815","full_name":"tks18/xl-pq-handler","owner":"tks18","description":"A Pythonic Power Query (.pq) File Manager for Excel \u0026 Power BI Automation","archived":false,"fork":false,"pushed_at":"2025-11-01T07:01:40.000Z","size":1755,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-06T21:09:22.433Z","etag":null,"topics":["analytics","automation","data","excel","power-query","powerbi","python","xlwings"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/xl-pq-handler/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tks18.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-24T11:11:31.000Z","updated_at":"2025-10-29T07:30:28.000Z","dependencies_parsed_at":"2025-10-24T17:39:00.054Z","dependency_job_id":null,"html_url":"https://github.com/tks18/xl-pq-handler","commit_stats":null,"previous_names":["tks18/xl-pq-handler"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tks18/xl-pq-handler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tks18%2Fxl-pq-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tks18%2Fxl-pq-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tks18%2Fxl-pq-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tks18%2Fxl-pq-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tks18","download_url":"https://codeload.github.com/tks18/xl-pq-handler/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tks18%2Fxl-pq-handler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"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":["analytics","automation","data","excel","power-query","powerbi","python","xlwings"],"created_at":"2025-10-28T05:52:45.431Z","updated_at":"2026-01-20T17:05:13.814Z","avatar_url":"https://github.com/tks18.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌈 xl-pq-handler\n\n\u003e 🧩 A Pythonic Power Query (.pq) File Manager for Excel \u0026 Power BI Automation\n\n[![PyPI Version](https://img.shields.io/pypi/v/xl-pq-handler.svg?color=4CAF50\u0026logo=python\u0026logoColor=white)](https://pypi.org/project/xl-pq-handler/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/xl-pq-handler.svg?color=blue)](https://pypi.org/project/xl-pq-handler/)\n[![License](https://img.shields.io/github/license/tks18/xl-pq-handler.svg?color=orange)](LICENSE)\n\n---\n\n### 🧠 What is `xl-pq-handler`?\n\n`xl-pq-handler` is a **Python UI App + library** built for developers, data analysts, and automation engineers who work with **Power Query (.pq)** files in Excel or Power BI.\n\nIt lets you:\n\n- 🔍 Parse, search, and index `.pq` scripts\n- 📋 Copy Power Query code to clipboard\n- 🪄 Insert queries directly into Excel workbooks\n- 🧾 Maintain YAML-based metadata (name, category, tags, description, version)\n- 🔁 Export, validate, and refresh PQ indexes\n- ⚡ Batch-insert queries for rapid Excel automation\n\nAll from Python. No manual clicks. No clutter. 🚀\n\n---\n\n\u003e Stop the cap. Managing Power Query `.pq` files is low-key a nightmare.\n\u003e\n\u003e **This tool is the ultimate glow-up for your M-code.** 💅\n\u003e\n\u003e It's not just a library; it's your new **Power Query IDE**.\n\n---\n\n## 💅 The Vibe Check: Before vs. After\n\n_(The PQ IDE You Didn't Know You Needed ✨)_\n\n| **Before xl-pq-handler 🫠**                   | **After xl-pq-handler 😎**                              |\n| :-------------------------------------------- | :------------------------------------------------------ |\n| Endless copy-pasting M-code                   | One-click insert into **any** open Excel workbook       |\n| Forgetting `fn_Helper_v3` needs `fn_Util_v1`  | **Dependency graph** shows you the whole family tree 🌳 |\n| decentralized file organization               | Auto-organized folders based on `category`              |\n| Editing metadata = Manual YAML torture        | Right-click -\\\u003e **Edit Metadata** -\\\u003e Save -\\\u003e Done ✅  |\n| \"Which file uses that API?\" -\\\u003e 🤷‍♂️            | **Data Sources tab** spills the tea ☕                  |\n| Blindly extracting queries from huge files    | **Preview** _before_ you extract, with syntax colors\\!  |\n| Updating one function in 5 workbooks manually | Edit once -\\\u003e Refresh UI -\\\u003e Insert where needed        |\n\nThis is that **main character energy** for your data workflow.\n\n---\n\n## ✨ Features That Absolutely Slap\n\nThis ain't your grandpa's script library. We got a whole ecosystem:\n\n### 🖥️ **The UI App (Your New Dashboard)**\n\n- Launch a **dedicated desktop app** straight from your terminal. No more sad script outputs.\n- Visually browse, search, and filter your _entire_ `.pq` library like a pro.\n- It's got that dark mode aesthetic. You know the vibes. ✨\n\n### 📥 **Smart Extract (\"Yoink\\! Button\")**\n\n- **From File:** Point it at _any_ `.xlsx` / `.xlsm` / `.xlsb` and instantly rip out all the Power Queries.\n- **From Open Workbook:** Got 5 Excels open? No stress. A **dropdown lists all open workbooks**. Pick one, hit extract. Easy.\n- **Preview Before Saving:** See the code (with syntax highlighting\\!), parameters, and data sources _before_ you commit to saving the `.pq` file. No more blind extraction\\!\n\n### 🪄 **Dependency-Aware Insert (\"Yeet Button\")**\n\n- Select a query (e.g., `FinalReport`). The app automatically knows it needs `GetSalesData` and `fn_FormatDate`.\n- It yeets **all required queries** into Excel _in the correct order_. 🤯\n- **Target Practice:** Don't just spray into the active workbook. Use the **dropdown to select _exactly_ which open workbook** gets the queries. Precision\\!\n\n### ✏️ **Edit Metadata + Auto-Sync (\"The Organizer\")**\n\n- Right-click a query -\\\u003e \"Edit Metadata.\"\n- Change the `name`, `tags`, `dependencies`, `description`, `version`.\n- **The Magic ✨:** Change the `category` from `Staging` to `Production`? The app **automatically moves the `.pq` file** to the `Production/` folder. Chef's kiss\\! 🤌\n\n### 💅 **Syntax Highlighting (\"Make it Pretty\")**\n\n- See your M-code in the **Preview tabs** (Library, Edit, Extract) with **VS Code-style syntax highlighting**. Keywords, functions, strings, comments – all colored up. ✨\n\n### 🧐 **Code Intelligence (\"The Brain\")**\n\n- **Parameter Peek:** Select a function query, and the **\"Parameters\" tab** shows its inputs, types (`any`, `text`, etc.), and if they're `optional`.\n- **Data Source Detective:** The **\"Data Sources\" tab** scans the code and lists out _all_ the external connections (`Sql.Database`, `Web.Contents`, `File.Contents`, etc.) and whether the source is a literal string or an input parameter. Big for security audits\\! 🕵️‍♀️\n- **Dependency Deets:**\n  - **Auto-Detect:** Click the button in the Edit dialog to automatically scan the code and suggest the `dependencies`. Saves _so_ much typing.\n  - **Visual Graph:** The **\"Graph\" tab** shows a slick tree view of a query's entire dependency chain. No more surprises. 🌳\n\n### 💻 **External Editor Escape Hatch (\"Send It\")**\n\n- Need to tweak the _actual_ M-code logic?\n- Right-click -\\\u003e \"Open in Editor.\"\n- Instantly opens the `.pq` file in **VS Code** (if it's in your PATH) or falls back to Notepad. Edit, save, hit refresh in the UI. Seamless.\n\n### 🤖 **Python Backend (`PQManager`)**\n\n- All the power, none of the clicks. Import `PQManager` into your own Python automation scripts.\n- Headless extraction, insertion, index building – you name it. Perfect for CI/CD or scheduled tasks.\n\n---\n\n## 📦 Get it Already (Installation)\n\n```bash\npip install xl-pq-handler\n```\n\n_(This single command grabs everything you need: `customtkinter`, `xlwings`, `pydantic`, `pyyaml`, `pandas`, `filelock` – the whole squad.)_\n\n---\n\n## 🚀 How to Vibe\n\n### 1\\. The Main Way (The UI) 💅\n\nThis is the main event. Open your terminal:\n\n```bash\n\n# Better launch - point it at your actual PQ repo folder\npython -m xl_pq_handler \"D:\\Path\\To\\Your\\PowerQuery_Repo\"\n\n# Or even better way\npqmagic \"D:\\Path\\To\\Your\\PowerQuery_Repo\"\n```\n\nNow just... use the app. Click around. It's built different. 😎\n\nThen just... click buttons. It's that easy.\n\n### 2\\. 🤓 Script Kiddie Corner (Python Usage)\n\nFor your `main.py` automation scripts, use the `PQManager`.\n\n```python\nfrom xl_pq_handler import PQManager\n\n# Point manager at your repo\nmanager = PQManager(r\"D:\\Path\\To\\Your\\PowerQuery_Repo\")\n\n# Rebuild index (always a good move)\nmanager.build_index()\n\n# ---- EXAMPLE: INSERT INTO SPECIFIC WORKBOOK ----\ntarget_workbook = \"Monthly_Report_WIP.xlsx\" # Must be open!\nqueries_needed = [\"Calculate_KPIs\", \"Generate_Summary\"]\n\ntry:\n    manager.insert_into_excel(\n        names=queries_needed,\n        workbook_name=target_workbook # \u003c-- Target acquired 🎯\n    )\n    print(f\"🚀 Sent queries to {target_workbook}. Mission accomplished.\")\nexcept Exception as e:\n    print(f\"😭 Insert failed: {e}\")\n\n# ---- EXAMPLE: EXTRACT FROM FILE ----\nsource_file = r\"C:\\Downloads\\NewDataSource.xlsx\"\ntry:\n    manager.extract_from_excel(category=\"Downloaded\", file_path=source_file)\n    print(f\"✅ Successfully yoinked queries from {source_file}!\")\nexcept Exception as e:\n    print(f\"💀 Extraction failed: {e}\")\n```\n\n---\n\n## 📁 The Drip (File Structure)\n\nThis is how you organize your repo. The app does the rest.\n\n```\nMy-Power-Query-Repo/\n│\n├── index.json          \u003c-- The app makes this. Don't touch.\n│\n├── API/                \u003c-- \"API\" Category\n│   ├── Get_API_Data.pq\n│   └── fn_Get_Credentials.pq\n│\n├── Helpers/            \u003c-- \"Helpers\" Category\n│   ├── fn_Format_Date.pq\n│   └── fn_Safe_Divide.pq\n│\n└── Reports/            \u003c-- \"Reports\" Category\n    └── Final_Sales_Report.pq\n```\n\nEach `.pq` file is just M-code with a **YAML \"frontmatter\"** block at the top. This is the metadata.\n\n```yaml\n---\nname: Clean_RawSales          # The query's name in Excel/PBI\ncategory: Staging             # Matches the folder name (keep it sync'd!)\ntags: [cleaning, sales, raw]  # Searchable tags\ndependencies:                 # List other queries *this one* calls\n  - fn_FormatDate\ndescription: Cleans and transforms the raw monthly sales data dump. # What it does\nversion: 2.1                  # Your version number\n---\n\nlet                           # Start of your actual M-code\n    Source = Csv.Document(File.Contents(\"path/to/raw.csv\"), ...),\n    #\"Formatted Date\" = fn_FormatDate(Source, \"OrderDate\")\nin\n    #\"Formatted Date\"\n```\n\n---\n\n## 📜 License\n\nThis project is licensed under the **GNU-GPL 3.0 License**. Go wild.\n\n---\n\n## 💚 Credits\n\nMade by **Sudharshan TK** (tks18)\n\nIf this tool just saved your workflow, give it a ⭐ **Star on [GitHub](https://github.com/tks18/xl-pq-handler)\\!**\n\n---\n\n\u003e ⚡ _“Automate the boring Power Query stuff — one `.pq` at a time.”_\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftks18%2Fxl-pq-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftks18%2Fxl-pq-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftks18%2Fxl-pq-handler/lists"}