Metadata-Version: 2.3
Name: corelibs-requests
Version: 1.0.0
Summary: CoreLibs Requests handling
Author: Clemens Schwaighofer
Author-email: Clemens Schwaighofer <clemens.schwaighofer@omc.com>
Requires-Dist: requests>=2.32.5
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# CoreLibs Python Requests

This is part of the Python CoreLibs

## Overview

Simple requests wrapper

## Install

```sh
uv add --index opj-pypi=https://git.egplusww.jp/api/packages/PyPI/pypi/simple/ corelibs-<project_name>
```

## Usage

This project has

- corelibs_requests.caller
- corelibs_requests.auth_helpers

### corelibs_requests.auth_helpers

```py
from corelibs_requests.auth_helpers import basic_auth
```

#### basic_auth

Builds a base64 encoded string for Basic auth

```py
def basic_auth(username: str, password: str) -> str:
```

Example:

```py
from corelibs_requests.auth_helpers import basic_auth

print(basic_auth("user", "pass"))
```

Will output

```txt
Basic dXNlcjpwYXNz
```

### from corelibs_requests.caller

This is a wraper around the requests library

```py
from corelibs_requests.caller import Caller, ErrorResponse
```

#### Caller init

To initial the class

```py
Caller(
    header: dict[str, str] | None = None,
    timeout: int = 20,
    proxy: ProxyConfig | None = None,
    verify: bool = True,
    ca_file: str | None = None
)
```

- header is a key, value dictionary list that will be used for the header arugment in each call, for example an authentication token can be set here
- timeout: int value for timeout, if not set will use 20s
- proxy: Proxy config dictionary, see "ProxyConfig" below
- verify: if set to False will not verify any SSL certificates
- ca_file: override the internal default ca_file

The following calls are avaiable

- get
- post
- put
- patch
- delete

See below for each calls setup. Each call will return a requests.Response or the class ErrorResponse. See below for error response

For "get" and "delete" no data parameter exists

For data, the content will be transferred as json data automatically, no other type is supported at the moment

##### for the ProxyConfig "proxy" argument

The proxy config entry must be

```py
{
    type: "socks5",
    host: "hostname or ip address"
    port: "port number"
}
```

##### ErrorResponse layout

The following entries can be found

- code: int number for the error, these are not HTTP response codes
  - 100: unexpected action (if not get, post, put, patch or delete)
  - 200: invalid URL
  - 300: timeout
  - 400: connection error
- message: The error message for the above code
- action: which action was called
- url: the url that was called (does not include parameters or content)
- exception_name: if an exception was thrown (error >100) the name is stored here
- exception_trace: the exceptio message is stored here

#### get

Sends a GET request

```py
def get(
    self,
    url: str,
    params: dict[str, Any] | None = None,
    timeout: int | None = None
) -> requests.Response | ErrorResponse:
```

#### post

Sends a POST request

```py
def post(
    self,
    url: str,
    data: dict[str, Any] | None = None,
    params: dict[str, Any] | None = None,
    timeout: int | None = None
) -> requests.Response | ErrorResponse:
```

#### put

Sends a PUT request

```py
def put(
    self,
    url: str,
    data: dict[str, Any] | None = None,
    params: dict[str, Any] | None = None,
    timeout: int | None = None
) -> requests.Response | ErrorResponse:
```

#### patch

Sends a PATCH request

```py
def patch(
    self,
    url: str,
    data: dict[str, Any] | None = None,
    params: dict[str, Any] | None = None,
    timeout: int | None = None
) -> requests.Response | ErrorResponse:
```

#### delete

Sends a DELETE request

```py
def delete(
    self,
    url: str,
    params: dict[str, Any] | None = None,
    timeout: int | None = None
) -> requests.Response | ErrorResponse:
```

## Development

### UV setup

uv must be [installed](https://docs.astral.sh/uv/getting-started/installation/)

### Python venv setup

After clone, run the command below to install all dependenciss

```sh
uv sync
```

### Build and Publish

```sh
uv build
uv publish --index opj-pypi --token <gitea token>
```

### Python tests

All python tests are the tests/ folder. They are structured by the source folder layout

run them with

```sh
uv run pytest
```

Get a coverate report

```sh
uv run pytest --cov=<project>
uv run pytest --cov=<project> --cov-report=term-missing
```

### Other tests

In the test-run folder usage and run tests are located, runt them below

```sh
uv run test-run/<script>
```
