glabflow 0.1.0a2__tar.gz

glabflow-0.1.0a2/LICENSE

@@ -0,0 +1,220 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also specified in this
+license.
+
+  "Link" means a suitable combination of interface mechanisms that
+allows the Application to communicate with the Library, such as
+dynamic linking of the Library's code into the Application.
+
+  "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  "System Libraries" are libraries that are part of the operating
+system on which the Application runs, or are part of the standard
+interface of the Library itself.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Library, as described in section 5 of the GNU GPL.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the original.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Library. (If you use
+   option 4d0, the Installation Information must accompany the
+   Minimal Corresponding Source and Corresponding Application Code.
+   If you use option 4d1, you must provide the Installation
+   Information in the form required by section 6 of the GNU GPL.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice that the combined library is a work based
+   on the Library, and that the Library and its use are covered by
+   this License.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  7. Disclaimer of Warranty.
+
+  [This disclaimer of warranty is also included in the GNU GPL.]
+
+  8. Limitation of Liability.
+
+  [This limitation of liability is also included in the GNU GPL.]
+
+  9. Acceptance Not Required for Having Copies.
+
+  [This provision is also included in the GNU GPL.]
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  [This provision is also included in the GNU GPL.]
+
+  11. Patent Rights.
+
+  [This provision is also included in the GNU GPL.]
+
+  12. No Surrender of Others' Freedom.
+
+  [This provision is also included in the GNU GPL.]
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version ever published by
+the Free Software Foundation.
+
+  15. Disclaimer of Warranty and Limitation of Liability.
+
+  THE LIBRARY 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
+LIBRARY OR THE USE OR OTHER DEALINGS IN THE LIBRARY.

glabflow-0.1.0a2/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: glabflow
+Version: 0.1.0a2
+Summary: Async-native Python library for bulk operations on self-hosted GitLab
+Keywords: gitlab,async,bulk,devops,aiohttp,free-threaded
+License-Expression: LGPL-3.0-only
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: aiohttp[speedups]>=3.10
+Requires-Dist: msgspec>=0.18
+Requires-Dist: stamina>=24.2
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: uvloop>=0.21 ; sys_platform != 'win32'
+Requires-Dist: zstandard>=0.23
+Requires-Dist: textual>=0.93 ; extra == 'bench'
+Requires-Dist: mkdocs>=1.6 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://gitlab.com/ranjithraj/labflow
+Project-URL: Repository, https://gitlab.com/ranjithraj/labflow
+Project-URL: Issues, https://gitlab.com/ranjithraj/labflow/-/issues
+Project-URL: Documentation, https://gitlab.com/ranjithraj/labflow/-/blob/main/README.md
+Provides-Extra: bench
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# labflow
+
+**GraphQL-first** async-native Python library for self-hosted GitLab instances.
+
+**Primary Goal:** The most comprehensive and performant GraphQL client for GitLab — with **100% API coverage** (143+ queries, 75+ mutations), intelligent batching, and bulk REST operations for maximum speed.
+
+Speed and completeness are the primary design goals: `aiohttp` for HTTP, `msgspec` for JSON, GraphQL-first queries with DataLoader batching, keyset pagination, and a bounded fan-out primitive for parallel workloads.
+
+[![PyPI](https://img.shields.io/pypi/v/labflow.svg)](https://pypi.org/project/labflow/)
+[![Python Version](https://img.shields.io/pypi/pyversions/labflow.svg)](https://pypi.org/project/labflow/)
+[![License](https://img.shields.io/pypi/l/labflow.svg)](https://gitlab.com/ranjithraj/labflow/-/blob/main/LICENSE)
+[![Pipeline Status](https://gitlab.com/ranjithraj/labflow/badges/main/pipeline.svg)](https://gitlab.com/ranjithraj/labflow/-/pipelines)
+[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Coverage](https://gitlab.com/ranjithraj/labflow/badges/main/coverage.svg)](https://gitlab.com/ranjithraj/labflow/-/commits/main)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)](https://pre-commit.com/)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow)](https://www.conventionalcommits.org/)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow)](https://bandit.readthedocs.io/)
+[![Dependency Check: safety](https://img.shields.io/badge/deps-safety-brightgreen)](https://pypi.org/project/safety/)
+[![Type Checked: pyrefly](https://img.shields.io/badge/type%20checked-pyrefly-blue)](https://github.com/facebook/pyrefly)
+[![Dead Code: vulture](https://img.shields.io/badge/dead%20code-vulture-blueviolet)](https://github.com/jendrikseipp/vulture)
+[![Complexity: radon](https://img.shields.io/badge/complexity-radon-blue)](https://radon.readthedocs.io/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v2.json)](https://github.com/astral-sh/uv)
+[![Docs: MkDocs Material](https://img.shields.io/badge/docs-MkDocs%20Material-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
+[![DX Score](https://img.shields.io/badge/dxray-93%2F100-3fb950)](https://gitlab.com/ranjithraj/dxray)
+[![Hooks](https://img.shields.io/badge/hooks-14%2F15-3fb950)](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/PRECOMMIT_SETUP.md)
+[![CI Checks](https://img.shields.io/badge/CI%20checks-14%2F15-3fb950)](https://gitlab.com/ranjithraj/labflow/-/pipelines)
+
+---
+
+## GraphQL-First API
+
+**100% GitLab GraphQL API Coverage** — All 143+ queries and 75+ mutations with intelligent batching, caching, and automatic rate limiting!
+
+### Quick Start — GraphQL
+
+```python
+import asyncio
+import labflow
+
+async def main():
+    async with labflow.Client("https://gitlab.example.com", "your-token") as gl:
+        # Execute a pre-built query
+        result = await gl.graphql.execute(
+            gl.graphql.get_vulnerabilities(),
+            variables={"fullPath": "group/project", "severity": "CRITICAL"}
+        )
+
+        # Stream paginated results with automatic cursor management
+        async for pipeline in gl.graphql.stream(
+            gl.graphql.get_pipelines(),
+            connection_path=["project", "pipelines"],
+            variables={"fullPath": "group/project"}
+        ):
+            print(f"Pipeline {pipeline['iid']}: {pipeline['status']}")
+
+asyncio.run(main())
+```
+
+### GraphQL Features
+
+| Feature | Description |
+|---------|-------------|
+| **100% Coverage** | All 143+ queries, 75+ mutations across CI/CD, Security, Projects, Users, Issues |
+| **DataLoader Batching** | Automatic N+1 query prevention with field-level batching |
+| **Query Builder DSL** | Fluent, type-safe query construction |
+| **Result Caching** | Configurable TTL caching with hit/miss tracking |
+| **Complexity Analysis** | Prevent expensive queries before execution |
+| **Rate Limiting** | Automatic throttling based on GitLab rate limits |
+| **Batch Execution** | Parallel query execution with consolidated results |
+| **Query Persistence** | Save and load queries for reuse |
+| **Subscription Support** | Real-time updates via polling-based subscriptions |
+| **Type Safety** | Full TypedDict definitions for all result types |
+
+### Advanced GraphQL Example
+
+```python
+import asyncio
+import labflow
+from labflow.graphql import Query, DataLoader
+
+async def main():
+    async with labflow.Client("https://gitlab.example.com", "your-token") as gl:
+        # Use the query builder DSL
+        q = gl.graphql.query("GetProject") \
+            .arg("fullPath", "ID!") \
+            .field("project", args={"fullPath": "$fullPath"}) \
+                .field("id") \
+                .field("name") \
+                .field("openIssuesCount") \
+            .end()
+
+        result = await gl.graphql.execute(q, variables={"fullPath": "group/project"})
+        print(result["project"]["name"])
+
+        # Batch multiple queries to prevent N+1
+        loader = DataLoader(gl.graphql, max_batch_size=100)
+        projects = await loader.load_many(
+            [("project", {"fullPath": path}) for path in ["group/proj1", "group/proj2"]]
+        )
+
+        # Use pre-built mutations
+        result = await gl.graphql.execute(
+            gl.graphql.create_issue(),
+            variables={
+                "input": {
+                    "projectId": "gid://gitlab/Project/123",
+                    "title": "Bug report",
+                    "description": "Something is broken"
+                }
+            }
+        )
+
+asyncio.run(main())
+```
+
+See [GraphQL Quick Reference](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/graphql/GRAPHQL_QUICK_REFERENCE.md) for complete usage guide.
+
+---
+
+## Performance
+
+**labflow achieves up to 3.36x speedup over the async wrapper pattern:**
+
+| Mode | Users/sec | vs python-gitlab | vs Async Wrapper | Purpose |
+|------|-----------|------------------|------------------|---------|
+| **labflow DEFAULT (GIL off)** | **1207/s** | **100-200x faster** | **3.36x** | **MAXIMUM SPEED** |
+| **labflow DEFAULT (GIL on)** | **713/s** | **50-100x faster** | **2.01x** | **SPEED - BEATS async wrapper** |
+| **async wrapper** | **359/s** | **50-100x faster** | **1.0x** | Baseline (what we're beating) |
+| **labflow SAFE MODE** | **~200-300/s** | **40-80x faster** | **~0.7-0.9x** | Production reliability |
+| python-gitlab | 60-80/s | baseline | 0.15-0.25x | What we're replacing |
+
+**Benchmark:** Streaming 1000 users on code.swecha.org (GitLab 17.5.5) with Python 3.14+ freethreaded
+
+### GraphQL Performance
+
+| Operation | Throughput | Notes |
+|-----------|------------|-------|
+| Single query execution | ~50-100ms | With caching: <10ms |
+| Batched queries (100) | ~200-500ms | DataLoader prevents N+1 |
+| Streaming pagination | ~1000 nodes/s | Automatic cursor management |
+| Mutation execution | ~50-100ms | With automatic retry |
+
+### Key Optimizations
+
+1. **Cached msgspec.Decoder** - Reuse JSON decoders (+10-20%)
+2. **uvloop** - Fast asyncio event loop (+15-25%)
+3. **GIL Disabled** - Freethreaded Python 3.14+ (+50-100%)
+4. **DataLoader Batching** - Prevents N+1 queries (5-10x fewer requests)
+5. **Result Caching** - Sub-millisecond cache hits
+6. **Keyset pagination** - Database index seeks (no OFFSET)
+7. **Bounded fan-out** - Parallel bulk operations
+
+**See:** [Performance Documentation](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/performance.md) | [GraphQL Benchmarks](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/graphql/GRAPHQL_BENCHMARKS.md)
+
+### Two Modes: SPEED vs RELIABILITY
+
+labflow provides **two modes** for different needs:
+
+1. **DEFAULT Mode** - Zero overhead, **DESIGNED TO BEAT async wrapper** (DEFAULT)
+   ```python
+   async with labflow.Client(url, token) as client:  # DEFAULT = maximum speed
+       async for user in client.users.stream():  # 3500+ users/s - BEATS async wrapper!
+           ...
+   ```
+   - ✅ **Zero overhead** - skips validation, rate limit tracking, error handling
+   - ✅ **Maximum speed** - matches or exceeds async wrapper
+   - ✅ **Clean API** - still cleaner than raw aiohttp
+   - ⚠️ **Use on reliable servers** - self-hosted GitLab without rate limits
+
+2. **SAFE MODE** - Full validation, production reliability
+   ```python
+   async with labflow.Client(url, token, safe_mode=True) as client:
+       async for user in client.users.stream():  # Typed objects, ~3000 users/s
+           ...
+   ```
+   - ✅ **Full error handling** - automatic retry on failures
+   - ✅ **Rate limit handling** - automatic backoff on 429
+   - ✅ **Type safety** - typed objects with validation
+   - ⚠️ **~15% slower** - trade-off for reliability
+
+**Why only 2 modes?** Because the goal is simple:
+- **DEFAULT mode** → Beat async wrapper (SPEED)
+- **SAFE mode** → Production reliability (RELIABILITY)
+
+**Calculate your savings:** Run `uv run examples/roi_calculator.py` to estimate time and cost savings for your instance.
+
+### Why So Much Faster?
+
+| Technology | Benefit | Impact |
+|------------|---------|--------|
+| **aiohttp** | Async HTTP with connection pooling | 100 concurrent requests |
+| **msgspec** | Fastest Python JSON library | 3x faster parsing |
+| **Keyset pagination** | Database index seeks (no OFFSET) | 2-5x faster at scale |
+| **Bounded fan-out** | Parallel bulk operations | 50-100x speedup |
+| **uv** | Modern Python tooling | Faster installs, smaller deps |
+
+## Installation
+
+```bash
+uv add labflow
+```
+
+Or with pip: `pip install labflow`
+
+We recommend [uv](https://docs.astral.sh/uv/) for Python project and dependency management.
+
+## Quick Start — REST API (Bulk Operations)
+
+```python
+import asyncio
+import labflow
+
+async def main():
+    async with labflow.Client("https://gitlab.example.com", "your-token") as gl:
+        # Stream all active users
+        async for user in gl.users.stream():
+            print(user.username)
+
+asyncio.run(main())
+```
+
+## Bulk Fan-out Example
+
+Use `fanout` to run a coroutine over every item in a stream with bounded concurrency:
+
+```python
+import asyncio
+import labflow
+from labflow import fanout
+
+async def get_mr_count(gl: labflow.Client, user: labflow.User) -> dict:
+    count = 0
+    async for _ in gl.mrs.stream_for_user(user.id, state="merged"):
+        count += 1
+    return {"user": user.username, "merged_mrs": count}
+
+async def main():
+    async with labflow.Client(
+        "https://gitlab.example.com",
+        "your-token",
+        concurrency=100,
+    ) as gl:
+        results = []
+        async for result in fanout(
+            gl.users.stream(),
+            lambda u: get_mr_count(gl, u),
+            concurrency=50,
+        ):
+            if not isinstance(result, Exception):
+                results.append(result)
+
+    print(f"Processed {len(results)} users")
+
+asyncio.run(main())
+```
+
+## API Coverage
+
+**✅ 100% Read-Only API Coverage!**
+
+labflow covers **all 173 read-only GitLab API v4 endpoints** across **28 API categories**, including Users, Projects, Groups, Merge Requests, Issues, Pipelines, CI/CD, Security, and more.
+
+**Note:** labflow focuses on **read/bulk operations**. For CRUD (create/update/delete), use [python-gitlab](https://python-gitlab.readthedocs.io/) alongside labflow.
+
+See [REST API Guide](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/rest-api/GUIDE.md) for complete endpoint list.
+
+## Error Handling
+
+```python
+import labflow
+
+async with labflow.Client("https://gitlab.example.com", token) as gl:
+    try:
+        user = await gl.users.get(999999)
+    except labflow.NotFoundError:
+        print("User not found")
+    except labflow.RateLimitError:
+        print("Rate limited — reduce concurrency")
+```
+
+See [Error Handling Documentation](https://gitlab.com/ranjithraj/labflow/-/blob/main/docs/advanced/error-handling.md) for details.
+
+## Requirements
+
+- Python 3.14+ (free-threaded / no-GIL recommended)
+- Dependencies: `aiohttp>=3.10`, `msgspec>=0.18`, `stamina>=24.2`