Gidgetlab

https://gidgetlab.readthedocs.io/en/latest/
Admin
Gidgetlab is an async library for calling GitLab's API with support for webhook handling and...
Tokens:11,245
Snippets:124
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install gidgetlab

Source: https://gidgetlab.readthedocs.io/en/latest?badge=latest

Installs the gidgetlab package using pip. Requires Python 3.8 or above.

```Shell
python3 -m pip install gidgetlab

```

--------------------------------

### Install gidgetlab with aiohttp support

Source: https://gidgetlab.readthedocs.io/en/latest?badge=latest

Installs gidgetlab with extra dependencies for web server support, specifically aiohttp.

```Shell
python3 -m pip install gidgetlab[aiohttp]

```

--------------------------------

### Install gidgetlab with aiohttp support

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/index.rst.txt

Install gidgetlab with extra dependencies for web server support, specifically aiohttp. Other options like httpx or tornado can be specified similarly.

```shell
python3 -m pip install gidgetlab[aiohttp]
```

--------------------------------

### Create and run a GitLabBot for webhook handling

Source: https://gidgetlab.readthedocs.io/en/latest/aiohttp.html

Shows how to instantiate a GitLabBot, register a webhook event handler, and start the bot. Webhook secret and access token are retrieved from environment variables if not provided.

```python
from gidgetlab.aiohttp import GitLabBot

bot = GitLabBot("username")

# Register a callack for a webhook event
@bot.router.register("Issue Hook", action="open")
async def issue_opened_event(event, gl, *args, **kwargs):
    url = f"/projects/{event.project_id}/issues/{event.object_attributes['iid']}/notes"
    message = f"Thanks for the report @{event.data['user']['username']}! I will look into it ASAP! (I'm a bot)."
    await gl.post(url, data={"body": message})

bot.run()
```

--------------------------------

### GitLabBot Example: Respond to Issue Opened Event

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/index.rst.txt

This example demonstrates how to create a GitLab bot using gidgetlab.aiohttp that responds to 'Issue Hook' events when an issue is opened. It posts a comment back to the issue.

```python
from gidgetlab.aiohttp import GitLabBot

bot = GitLabBot("beenje")


@bot.router.register("Issue Hook", action="open")
async def issue_opened_event(event, gl, *args, **kwargs):
    """Whenever an issue is opened, greet the author and say thanks."""
    url = f"/projects/{event.project_id}/issues/{event.object_attributes['iid']}/notes"
    message = f"Thanks for the report @{event.data['user']['username']}! I will look into it ASAP! (I'm a bot)."
    await gl.post(url, data={"body": message})
```

```python
if __name__ == "__main__":
    bot.run()
```

--------------------------------

### Callback Signature Example

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

Registered callbacks must be awaitable and accept at least one 'Event' instance. Additional arguments can be passed down during dispatch.

```python
async def callback(event, *args, **kwargs):
    ...
```

--------------------------------

### Using the Register Decorator

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

The register() decorator provides a concise way to add callbacks. This example registers a callback for 'Issue Hook' events with the action 'open' using the decorator syntax.

```python
router = gidgetlab.routing.Router()

@router.register("Issue Hook", action="open")
async def callback(event):
    ...
```

--------------------------------

### GitLab API GET Request (Multiple Items)

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Retrieve all items from a GitLab API endpoint, automatically handling pagination. Use this for GET calls that can return multiple values.

```python
async for item in gl.getiter(url, params={}):
    # process item
```

--------------------------------

### GitLab Bot Responding to Issue Opens

Source: https://gidgetlab.readthedocs.io/en/latest?badge=latest

Example of a GitLab bot using aiohttp to respond to 'issue open' webhooks. It posts a greeting message to the issue.

```Python
from gidgetlab.aiohttp import GitLabBot

bot = GitLabBot("beenje")


@bot.router.register("Issue Hook", action="open")
async def issue_opened_event(event, gl, *args, **kwargs):
    """Whenever an issue is opened, greet the author and say thanks."""
    url = f"/projects/{event.project_id}/issues/{event.object_attributes['iid']}/notes"
    message = f"Thanks for the report @{event.data['user']['username']}! I will look into it ASAP! (I'm a bot)."
    await gl.post(url, data={"body": message})


if __name__ == "__main__":
    bot.run()

```

--------------------------------

### Registering a Callback for Opened Issues

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

Use the add() method to register a callback for a specific event type and object attributes. This example registers a callback for 'Issue Hook' events where the action is 'open'.

```python
async def callback(event):
    ...

router.add(callback, "Issue Hook", action="open")
```

--------------------------------

### getitem

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Get a single item from GitLab. This is used for GET requests that are expected to return a single item. For requests that might return multiple values and require pagination, use getiter().

```APIDOC
## GET /templates/licenses/MIT

### Description
Retrieves a specific item from the GitLab API, typically a single resource.

### Method
GET

### Endpoint
/templates/licenses/MIT

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.

### Response
#### Success Response (200)
- **Any** - The decoded response body from the GitLab API.
```

--------------------------------

### getiter

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Get all items from a GitLab API endpoint. This method returns an asynchronous iterable that yields all items from the specified endpoint, automatically handling pagination.

```APIDOC
## GET (paginated)

### Description
Retrieves all items from a GitLab API endpoint, automatically handling pagination. Returns an asynchronous iterable.

### Method
GET

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.

### Response
#### Success Response (200)
- **AsyncGenerator[Any, None]** - An asynchronous generator yielding all items from the endpoint.
```

--------------------------------

### Initialize GitLabAPI with aiohttp ClientSession

Source: https://gidgetlab.readthedocs.io/en/latest/aiohttp.html

Demonstrates how to create a GitLabAPI instance using an aiohttp ClientSession. Ensure you have a valid access token.

```python
import aiohttp
import gidgetlab.aiohttp


async with aiohttp.ClientSession() as session:
    gl = gidgetlab.aiohttp.GitLabAPI(session, requester, 
                                     access_token=access_token)
    # Make your requests, e.g. ...
    data = await gl.getitem("/templates/licenses/MIT")
```

--------------------------------

### GitLabAPI Usage with httpx

Source: https://gidgetlab.readthedocs.io/en/latest/httpx.html

Demonstrates how to instantiate and use the GitLabAPI with httpx for making asynchronous requests to the GitLab API. Requires httpx and gidgetlab.httpx to be imported.

```python
import httpx
import gidgetlab.httpx


async with httpx.AsyncClient() as client:
    gl = gidgetlab.httpx.GitLabAPI(client, requester,
                                   access_token=access_token)
    # Make your requests, e.g. ...
    data = await gl.getitem("/templates/licenses/MIT")

```

--------------------------------

### Make a simple GitLab API request

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/abc.rst.txt

Use an instantiated GitLabAPI object to make a direct request to the GitLab API, such as fetching a license template. Assumes 'gl' is an implementation of GitLabAPI.

```python
# Assume `gl` has an implementation of GitLabAPI.
data = await gl.getitem("/templates/licenses/MIT")
```

--------------------------------

### gidgetlab.sansio.RateLimit.from_http

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Creates a RateLimit instance from the HTTP headers of a GitLab API response. It returns None if the rate limit information is not found in the headers.

```APIDOC
## RateLimit.from_http(_headers_)

### Description
Create a `RateLimit` instance from the HTTP headers of a GitLab API response. Returns `None` if the ratelimit is not found in the headers.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
Class Method

### Endpoint
Not specified

### Return Type
`Optional`[`RateLimit`]
```

--------------------------------

### Register multiple routers with GitLabBot

Source: https://gidgetlab.readthedocs.io/en/latest/aiohttp.html

Illustrates how to register multiple router instances with a GitLabBot after its initialization. This allows for modular handling of different webhook events.

```python
import gidgetlab.routing
from gidgetlab.aiohttp import GitLabBot

first_router = gidgetlab.routing.Router()
second_router = gidgetlab.routing.Router()

@first_router.register("Issue Hook", action="open")
async def issue_opened_event(event, gl, *args, **kwargs):
    ...

@second_router.register("Push Hook")
async def push_event(event, gl, *args, **kwargs):
    ...

bot = GitLabBot("username")
bot.register_routers(first_router, second_router)
bot.run()
```

--------------------------------

### Instantiate GitLabAPI with a private instance URL

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/abc.rst.txt

Instantiate GitLabAPI specifying a custom URL for a private GitLab instance. The 'url' parameter takes precedence over the GL_URL environment variable.

```python
gl = GitLabAPI(requester, url="https://mygitlab.example.com")
```

--------------------------------

### RateLimit.from_http

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Creates a RateLimit instance from the HTTP headers of a GitLab API response.

```APIDOC
## RateLimit.from_http

### Description
Creates a :class:`RateLimit` instance from the HTTP headers of a GitLab API response. Returns ``None`` if the ratelimit information is not found in the headers.

### Method
`RateLimit.from_http(headers)`

### Parameters
- **headers** (dict) - Required - The HTTP headers from the GitLab API response.

### Response
- **RateLimit or None** - A RateLimit object populated with rate limit details, or None if not present in headers.
```

--------------------------------

### GitLabAPI

Source: https://gidgetlab.readthedocs.io/en/latest/httpx.html

An implementation of gidgetlab.abc.GitLabAPI using httpx. It allows for making asynchronous requests to the GitLab API.

```APIDOC
## GitLabAPI

### Description
An implementation of `gidgetlab.abc.GitLabAPI` using httpx. It provides a way to interact with the GitLab API asynchronously.

### Class Signature
`gidgetlab.httpx.GitLabAPI(_client_, *args, **kwargs)`

### Usage Example
```python
import httpx
import gidgetlab.httpx

async with httpx.AsyncClient() as client:
    gl = gidgetlab.httpx.GitLabAPI(client, requester, access_token=access_token)
    data = await gl.getitem("/templates/licenses/MIT")
```

### Methods
This class implements methods from `gidgetlab.abc.GitLabAPI`, such as `getitem` for retrieving data from the API.
```

--------------------------------

### GitLabAPI

Source: https://gidgetlab.readthedocs.io/en/latest/aiohttp.html

An implementation of gidgetlab.abc.GitLabAPI using aiohttp. It allows making requests to the GitLab API.

```APIDOC
## Class GitLabAPI

### Description
An implementation of `gidgetlab.abc.GitLabAPI` using aiohttp.

### Usage
```python
import aiohttp
import gidgetlab.aiohttp


async with aiohttp.ClientSession() as session:
    gl = gidgetlab.aiohttp.GitLabAPI(session, requester, access_token=access_token)
    # Make your requests, e.g. ...
    data = await gl.getitem("/templates/licenses/MIT")
```

### Parameters
* `_session_` - An aiohttp ClientSession instance.
* `_*args` - Additional positional arguments.
* `**kwargs` - Additional keyword arguments, can be used to set a specific `url` and `api_version`.
```

--------------------------------

### create_headers

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Creates a dictionary of headers suitable for making authenticated requests to the GitLab API.

```APIDOC
## create_headers

### Description
Generates the necessary HTTP headers for making authenticated requests to the GitLab API, including the access token.

### Method
`create_headers(user_agent, access_token=None)`

### Parameters
- **user_agent** (str) - Required - A string to identify the client making the request.
- **access_token** (str) - Optional - The access token for authentication with the GitLab API.

### Response
- **dict** - A dictionary containing the headers for the API request.

### Request Example
```python
import requests

token = "your_access_token"
request_headers = create_headers("beenje", access_token=token)
url = "https://gitlab.com/api/v4/groups/gitlab-org/projects"
response = requests.get(url, headers=request_headers)
```
```

--------------------------------

### Router.add

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

Add an asynchronous callback for an event. The event_type argument corresponds to the gidgetlab.sansio.Event.event attribute of the event that the callback is interested in. The arbitrary keyword arguments is used as a key/value pair to compare against what is provided in gidgetlab.sansio.Event.object_attributes.

```APIDOC
## Router.add

### Description
Add an asynchronous callback for an event.

### Method
`Router.add(func, event_type, **object_attribute)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **func** (Callable) - The asynchronous callback function.
- **event_type** (string) - The type of the event.
- **object_attribute** (dict) - Key/value pairs to compare against event object attributes.

### Request Example
```python
async def callback(event):
    ...

router.add(callback, "Issue Hook", action="open")
```

### Response
#### Success Response (None)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Create RateLimit from HTTP Headers

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Constructs a RateLimit object from the headers of an HTTP response. Returns None if rate limit information is not present in the headers.

```python
_classmethod _from_http(_headers_)
```

--------------------------------

### Clone gidgetlab source code

Source: https://gidgetlab.readthedocs.io/en/latest?badge=latest

Clones the gidgetlab source code repository from GitLab using git.

```Shell
git clone https://gitlab.com/beenje/gidgetlab.git

```

--------------------------------

### GitLab GraphQL API Query

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Query the GitLab GraphQL API with a given query string and optional variables. The `variables` are passed as keyword arguments.

```python
result = await gl.graphql(query, var1=value1, var2=value2)
```

--------------------------------

### RedirectionException

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Specific exception for 3XX HTTP responses, indicating that the client should follow a redirection.

```APIDOC
## RedirectionException

### Description
Exception for 3XX HTTP responses.

### Parameters
#### Path Parameters
- **_status_code_** (int) - Required - The HTTP status code.

### Exception
_exception _gidgetlab.exceptions.RedirectionException(_status_code_ , _* args_)
```

--------------------------------

### Create Headers for GitLab API Request

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Generates the necessary headers for making authenticated requests to the GitLab API. Requires a username and access token.

```python
import requests

request_headers = create_headers("beenje", access_token=token)
url = "https://gitlab.com/api/v4/groups/gitlab-org/projects"
response = requests.get(url, headers=request_headers)
```

--------------------------------

### Router.register

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

A decorator that calls add() on the decorated function. This allows for registering callbacks using a decorator syntax.

```APIDOC
## Router.register

### Description
A decorator that calls `add()` on the decorated function.

### Method
`router.register(event_type, **object_attribute)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_type** (string) - The type of the event.
- **object_attribute** (dict) - Key/value pairs to compare against event object attributes.

### Request Example
```python
router = gidgetlab.routing.Router()

@router.register("Issue Hook", action="open")
async def callback(event):
    ...
```

### Response
#### Success Response (Callable)
Returns a callable that can be used as a decorator.

#### Response Example
```python
# The decorator itself returns a callable
```
```

--------------------------------

### Event.from_http

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Constructs an Event instance from an incoming HTTP request's headers and body. This is useful for processing webhook events sent by GitLab.

```APIDOC
## Event.from_http

### Description
Creates an Event instance from HTTP headers and body, optionally using a secret for verification. This is the primary method for processing incoming webhook events.

### Method
`Event.from_http(headers, body, secret=None)`

### Parameters
- **headers** (dict) - Required - The HTTP headers from the incoming request.
- **body** (bytes) - Required - The raw HTTP request body.
- **secret** (str) - Optional - The secret token used to verify the webhook signature.

### Response
- **Event** (object) - An instance of the Event class representing the webhook event.

### Request Example
```python
import os
import aiohttp.web

SECRET = os.environ["GL_SECRET_TOKEN"]

async def index(request):
    headers = request.headers
    body = await request.read()
    event = gidgetlab.Event.from_http(headers, body,
                                      secret=SECRET)
```
```

--------------------------------

### graphql

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Query the GraphQL API. This method allows for executing GraphQL queries against the GitLab GraphQL endpoint, with support for variables.

```APIDOC
## POST /api/graphql

### Description
Queries the GitLab GraphQL API.

### Method
POST

### Endpoint
/api/graphql

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.
- **variables** (dict) - Optional - A dictionary of variables to be used with the GraphQL query.

### Response
#### Success Response (200)
- **Any** - The decoded JSON response from the GraphQL API.
```

--------------------------------

### Event.from_http()

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Constructs an Event instance from HTTP headers and JSON body data. It performs content-type checks and event validation if headers are provided.

```APIDOC
## Event.from_http()

### Description
Constructs an `Event` instance from HTTP headers and JSON body data. The mapping providing the _headers_ is expected to support lowercase keys. Since this method assumes the body of the HTTP request is JSON, a check is performed for a content-type of “application/json”. If the content-type does not match, `BadRequest` is raised. If the appropriate headers are provided for event validation, then it will be performed unconditionally. Any failure in validation (including not providing a _secret_) will lead to `ValidationFailure` being raised.

### Method
`classmethod`

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import os
import aiohttp.web

SECRET = os.environ["GL_SECRET_TOKEN"]

async def index(request):
    headers = request.headers
    body = await request.read()
    event = gidgetlab.Event.from_http(headers, body,
                                      secret=SECRET)
```

### Response
#### Success Response (Event)
- **Event** (`gidgetlab.sansio.Event`): An instance of the Event class representing the GitLab webhook event.

#### Response Example
```json
{
  "example": "gidgetlab.sansio.Event object"
}
```
```

--------------------------------

### Router.dispatch

Source: https://gidgetlab.readthedocs.io/en/latest/routing.html

Call the appropriate asynchronous callbacks for the event. The provided event and any other arguments will be passed down to the callback unmodified.

```APIDOC
## Router.dispatch

### Description
Call the appropriate asynchronous callbacks for the event.

### Method
`async dispatch(event, *args, **kwargs)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event** (gidgetlab.sansio.Event) - The event to dispatch.
- **args** - Positional arguments to pass to the callback.
- **kwargs** - Keyword arguments to pass to the callback.

### Request Example
```python
await router.dispatch(event, arg1, kwarg1='value1')
```

### Response
#### Success Response (None)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Create Event from HTTP Request

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Use this method to create an Event object from an incoming HTTP request. Ensure the SECRET environment variable is set.

```python
import os
import aiohttp.web

SECRET = os.environ["GL_SECRET_TOKEN"]

async def index(request):
    headers = request.headers
    body = await request.read()
    event = gidgetlab.Event.from_http(headers, body,
                                     secret=SECRET)
```

--------------------------------

### post

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a POST request to GitLab. This method is used for creating resources or performing actions that require sending data to the API.

```APIDOC
## POST [URL]

### Description
Sends a POST request to a GitLab endpoint to create or modify resources.

### Method
POST

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.
#### Request Body
- **data** (object) - Required - An object that can be serialized to JSON, representing the data to be sent.

### Response
#### Success Response (200, 201, 202)
- **Any** - The decoded response body from the GitLab API.
```

--------------------------------

### GitLabAPI Class

Source: https://gidgetlab.readthedocs.io/en/latest/tornado.html

The GitLabAPI class provides an implementation of gidgetlab.abc.GitLabAPI using Tornado for asynchronous operations. It allows for making requests to the GitLab API with Tornado's event loop.

```APIDOC
## GitLabAPI Class

### Description
An implementation of `gidgetlab.abc.GitLabAPI` using Tornado.

### Class Signature
`gidgetlab.tornado.GitLabAPI(_requester_, *_ , access_token=None, url=None, api_version='v4', cache=None)`

### Parameters
#### Keyword-only Parameters
- `_requester_` - The requester object for making API calls.
- `access_token` (string) - Optional. The access token for authentication.
- `url` (string) - Optional. The base URL for the GitLab API.
- `api_version` (string) - Optional. The API version to use (defaults to 'v4').
- `cache` - Optional. A cache object for storing responses.
```

--------------------------------

### GitLabException

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

The base exception for all Gidgetlab-related errors. All other Gidgetlab exceptions inherit from this class.

```APIDOC
## GitLabException

### Description
Base exception for this library.

### Exception
_exception _gidgetlab.exceptions.GitLabException
```

--------------------------------

### Set private GitLab instance URL via environment variable

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/abc.rst.txt

Set the GL_URL environment variable to specify a custom URL for a private GitLab instance. This is overridden by the 'url' parameter during instantiation.

```bash
export GL_URL=https://mygitlab.example.com
```

--------------------------------

### head

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a HEAD request to GitLab. This is useful for retrieving only the headers from a GitLab endpoint, such as rate limit information, without fetching the response body.

```APIDOC
## HEAD [URL]

### Description
Sends a HEAD request to a GitLab endpoint to retrieve only the response headers.

### Method
HEAD

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.

### Response
#### Success Response (200)
- **Any** - The decoded response headers from the GitLab API.
```

--------------------------------

### GraphQLException

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Base exception for errors encountered when interacting with the GraphQL v4 API.

```APIDOC
## GraphQLException

### Description
Base exception for the GraphQL v4 API.

### Parameters
#### Path Parameters
- **_message_** (string) - Required - The error message.
- **_response_** (any) - Required - The response object from the GraphQL API.

### Exception
_exception _gidgetlab.exceptions.GraphQLException(_message_ , _response_)
```

--------------------------------

### GitLabBot Class

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/aiohttp.rst.txt

The GitLabBot class is a simple aiohttp web server designed to handle GitLab webhooks.

```APIDOC
## Class: GitLabBot

### Description
A simple aiohttp web server that handles GitLab webhooks.

### Members
This class has members that allow for the creation and management of a webhook-handling server. Refer to the source code for specific method signatures and functionalities.
```

--------------------------------

### Create Event object from HTTP request

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Use Event.from_http to parse incoming webhook data from HTTP headers and body into an Event object. Ensure the secret is provided for validation.

```python
import os
import aiohttp.web

SECRET = os.environ["GL_SECRET_TOKEN"]

async def index(request):
    headers = request.headers
    body = await request.read()
    event = gidgetlab.Event.from_http(headers, body,
                                      secret=SECRET)
```

--------------------------------

### GitLab API POST Request

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a POST request to the GitLab API. The `data` argument accepts a JSON-serializable object.

```python
result = await gl.post(url, params={}, data=json_data)
```

--------------------------------

### GitLabBroken

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Specific exception for 5XX HTTP responses, indicating a server-side error on GitLab's end.

```APIDOC
## GitLabBroken

### Description
Exception for 5XX HTTP responses.

### Parameters
#### Path Parameters
- **_status_code_** (int) - Required - The HTTP status code.

### Exception
_exception _gidgetlab.exceptions.GitLabBroken(_status_code_ , _* args_)
```

--------------------------------

### GitLab API HEAD Request

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a HEAD request to a GitLab endpoint to retrieve only the X-Gitlab-* headers, without the response body.

```python
headers = await gl.head(url, params={})
```

--------------------------------

### HTTPException

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

A general exception for representing HTTP responses. It captures the status code of the HTTP response.

```APIDOC
## HTTPException

### Description
A general exception to represent HTTP responses.

### Parameters
#### Path Parameters
- **_status_code_** (int) - Required - The HTTP status code.

### Exception
_exception _gidgetlab.exceptions.HTTPException(_status_code_ , _* args_)
```

--------------------------------

### put

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a PUT request to GitLab. This method is used for updating or replacing existing resources.

```APIDOC
## PUT [URL]

### Description
Sends a PUT request to a GitLab endpoint to update or replace an existing resource.

### Method
PUT

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.
#### Request Body
- **data** (object) - Optional - An object that can be serialized to JSON, representing the data to be sent. Defaults to an empty byte string.

### Response
#### Success Response (200, 201, 202)
- **Any** - The decoded response body from the GitLab API.
```

--------------------------------

### GraphQLAuthorizationFailure

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised for a 401 HTTP response, typically due to an invalid or expired OAuth token.

```APIDOC
## GraphQLAuthorizationFailure

### Description
401 HTTP response to a bad oauth token.

### Parameters
#### Path Parameters
- **_response_** (any) - Required - The response object from the GraphQL API.

### Exception
_exception _gidgetlab.exceptions.GraphQLAuthorizationFailure(_response_)
```

--------------------------------

### Direct GitLab API Item Retrieval

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Retrieve a single item from the GitLab API using its path. This method abstracts away lower-level HTTP details.

```python
data = await gl.getitem("/templates/licenses/MIT")
```

--------------------------------

### RateLimitExceeded

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised when a request is rejected because the API rate limit has been exceeded. It includes information about the rate limit.

```APIDOC
## RateLimitExceeded

### Description
Request rejected due to the rate limit being exceeded.

### Parameters
#### Path Parameters
- **_rate_limit_** (any) - Required - Information about the rate limit.

### Exception
_exception _gidgetlab.exceptions.RateLimitExceeded(_rate_limit_ , _* args_)
```

--------------------------------

### GitLab API PUT Request

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a PUT request to the GitLab API. The `data` argument accepts a JSON-serializable object, defaulting to empty bytes.

```python
result = await gl.put(url, params={}, data=json_data)
```

--------------------------------

### GitLabAPI Class

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/aiohttp.rst.txt

The GitLabAPI class is part of the aiohttp support module and is likely used for interacting with the GitLab API.

```APIDOC
## Class: GitLabAPI

### Description
Provides methods for interacting with the GitLab API using aiohttp.

### Members
This class has various members that allow for API calls. Refer to the source code for specific method signatures and functionalities.
```

--------------------------------

### gidgetlab.sansio.decipher_response

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Deciphers an HTTP response from the GitLab API. It takes the status code, headers, and body as input and returns the decoded body, rate limit information, and a URL for the next page of results if available. It also handles specific status codes and can process HEAD requests.

```APIDOC
## decipher_response(_status_code_, _headers_, _body_, _method ='')

### Description
Deciphers an HTTP response for a GitLab API request. The mapping providing the headers is expected to support lowercase keys. The parameters of this function correspond to the three main parts of an HTTP response: the status code, headers, and body. Assuming no errors which lead to an exception being raised, a 3-item tuple is returned. The first item is the decoded body (typically a JSON object, but possibly None or a string depending on the content type of the body). The second item is an instance of RateLimit based on what the response specified. The last item of the tuple is the URL where to request the next part of results. If there are no more results then None is returned. Do be aware that the URL can be a URI template and so may need to be expanded. The optional named parameter “method” is used to handle the response from the HTTP HEAD method. In a HEAD, the response contains no body and just the headers. So we return the headers in place of the body. If the status code is anything other than 200, 201, 202, or 204, then an appropriate `HTTPException` is raised.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
Not specified (typically used with GET, POST, PUT, DELETE, HEAD)

### Endpoint
Not specified

### Return Type
`Tuple`[`Any`, `Optional`[`RateLimit`], `Optional`[`str`]]
```

--------------------------------

### GraphQLResponseTypeError

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised when the GraphQL response has an unexpected content type, indicating a potential issue with the response format.

```APIDOC
## GraphQLResponseTypeError

### Description
The GraphQL response has an unexpected content type.

### Parameters
#### Path Parameters
- **_content_type_** (string) - Required - The unexpected content type received.
- **_response_** (any) - Required - The response object from the GraphQL API.

### Exception
_exception _gidgetlab.exceptions.GraphQLResponseTypeError(_content_type_ , _response_)
```

--------------------------------

### GitLab API PATCH Request

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a PATCH request to the GitLab API. The `data` argument accepts a JSON-serializable object.

```python
result = await gl.patch(url, params={}, data=json_data)
```

--------------------------------

### delete

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a DELETE request to GitLab. This method is used for removing resources.

```APIDOC
## DELETE [URL]

### Description
Sends a DELETE request to a GitLab endpoint to remove a resource.

### Method
DELETE

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.
#### Request Body
- **data** (object) - Optional - An object that can be serialized to JSON, representing the data to be sent. Defaults to an empty byte string.

### Response
#### Success Response (200, 201, 202, 204)
- **None** - Indicates successful deletion.
```

--------------------------------

### patch

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a PATCH request to GitLab. This method is used for partially updating existing resources.

```APIDOC
## PATCH [URL]

### Description
Sends a PATCH request to a GitLab endpoint to partially update an existing resource.

### Method
PATCH

### Endpoint
[URL of the endpoint]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Query string parameters to be included in the request.
#### Request Body
- **data** (object) - Required - An object that can be serialized to JSON, representing the data to be sent.

### Response
#### Success Response (200, 201, 202)
- **Any** - The decoded response body from the GitLab API.
```

--------------------------------

### BadGraphQLRequest

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised for 4XX HTTP responses from the GraphQL API, indicating a client-side error in the request.

```APIDOC
## BadGraphQLRequest

### Description
A 4XX HTTP response.

### Parameters
#### Path Parameters
- **_status_code_** (int) - Required - The HTTP status code.
- **_response_** (any) - Required - The response object from the GraphQL API.

### Exception
_exception _gidgetlab.exceptions.BadGraphQLRequest(_status_code_ , _response_)
```

--------------------------------

### GitLab API DELETE Request

Source: https://gidgetlab.readthedocs.io/en/latest/abc.html

Send a DELETE request to the GitLab API. The `data` argument accepts a JSON-serializable object, defaulting to empty bytes.

```python
await gl.delete(url, params={}, data=json_data)
```

--------------------------------

### Decipher GitLab API Response

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Parses the status code, headers, and body of an HTTP response from the GitLab API. Handles JSON, string, or None bodies and extracts rate limit information. Raises HTTPException for non-2xx/304 status codes. Can optionally process HEAD responses.

```python
gidgetlab.sansio.decipher_response(_status_code_ , _headers_ , _body_ , _method =''_)
```

--------------------------------

### BadRequest

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised for 4XX HTTP errors when the request is invalid. This indicates a client-side error in the request.

```APIDOC
## BadRequest

### Description
The request is invalid.
Used for 4XX HTTP errors.

### Parameters
#### Path Parameters
- **_status_code_** (int) - Required - The HTTP status code.

### Exception
_exception _gidgetlab.exceptions.BadRequest(_status_code_ , _* args_)
```

--------------------------------

### Decipher GitLab API Response

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Parses the status code, headers, and content of a GitLab API response to extract data and rate limit information. Handles rate limiting by waiting if necessary.

```python
# Assuming `response` contains a requests.Response object.
import datetime


status_code = response.status_code
headers = response.headers
body = response.content
data, rate, more = decipher_response(status_code, headers, body)
# Response details are in `data`.
if more:
    if not rate.remaining:
        now = datetime.datetime.now(datetime.tzinfo.utc)
        wait = rate.reset_datetime - now
        time.sleep(wait.total_seconds())
    response_more = requests.get(more, headers=request_headers)
    # Decipher `response_more` ...
```

--------------------------------

### decipher_response

Source: https://gidgetlab.readthedocs.io/en/latest/_sources/sansio.rst.txt

Parses the status code, headers, and body of a GitLab API response to extract data and rate limit information.

```APIDOC
## decipher_response

### Description
Deciphers a response from the GitLab API, extracting the main data payload, rate limit details, and a URL for fetching more data if available.

### Method
`decipher_response(status_code, headers, body)`

### Parameters
- **status_code** (int) - Required - The HTTP status code of the response.
- **headers** (dict) - Required - The HTTP headers of the response.
- **body** (bytes) - Required - The raw content of the response body.

### Response
- **tuple** - A tuple containing:
    - **data** (any) - The deciphered data from the response body.
    - **rate** (RateLimit) - A RateLimit object containing rate limit information.
    - **more** (str or None) - A URL to fetch more data, or None if no more data is available.

### Request Example
```python
# Assuming `response` contains a requests.Response object.
import datetime

status_code = response.status_code
headers = response.headers
body = response.content
data, rate, more = decipher_response(status_code, headers, body)

if more:
    if not rate.remaining:
        now = datetime.datetime.now(datetime.tzinfo.utc)
        wait = rate.reset_datetime - now
        time.sleep(wait.total_seconds())
    response_more = requests.get(more, headers=request_headers)
    # Decipher `response_more` ...
```
```

--------------------------------

### InvalidField

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised when a specific field in the request is invalid, typically indicated by a 422 HTTP Response. Details of invalid fields are available in the 'errors' attribute.

```APIDOC
## InvalidField

### Description
A field in the request is invalid.
Represented by a 422 HTTP Response. Details of what fields were invalid are stored in the errors attribute.

### Parameters
#### Path Parameters
- **_errors_** (any) - Required - Details of the invalid fields.

### Exception
_exception _gidgetlab.exceptions.InvalidField(_errors_ , _* args_)
```

--------------------------------

### Decipher GitLab API response

Source: https://gidgetlab.readthedocs.io/en/latest/sansio.html

Use decipher_response to parse the status code, headers, and content of a GitLab API response. It returns the data payload, rate limit information, and a boolean indicating if there's more data.

```python
# Assuming `response` contains a requests.Response object.
import datetime


status_code = response.status_code
headers = response.headers
body = response.content
data, rate, more = decipher_response(status_code, headers, body)
```

--------------------------------

### QueryError

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised when an error occurs during the processing of a GraphQL v4 query.

```APIDOC
## QueryError

### Description
An error occurred while attempting to handle a GraphQL v4 query.

### Parameters
#### Path Parameters
- **_response_** (any) - Required - The response object from the GraphQL API.

### Exception
_exception _gidgetlab.exceptions.QueryError(_response_)
```

--------------------------------

### ValidationFailure

Source: https://gidgetlab.readthedocs.io/en/latest/exceptions.html

Raised when a webhook event fails validation. This indicates that the incoming data does not conform to the expected structure or rules.

```APIDOC
## ValidationFailure

### Description
An exception representing failed validation of a webhook event.

### Exception
_exception _gidgetlab.exceptions.ValidationFailure
```
Tokens:
Raw