Metadata-Version: 2.4
Name: py_client_cap
Version: 0.1.7
Summary: Client Python e libreria REST API per la gestione automatizzata di database tramite backend PHP CRUD (codice su Git). Integrazione rapida via HTTP e JSON
Home-page: https://www.newstechnology.eu
Author: Daniele Frulla
Author-email: daniele.frulla@newstechnology.eu
Keywords: python,php,crud,rest-api,database-manager,git-repo,php-crud-api
Description-Content-Type: text/markdown
Requires-Dist: requests==2.34.2
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: summary

# Libreria Python Client CRUD PHP API

Questo documento racchiude tutto il necessario per utilizzare la libreria: le istruzioni d'uso (README), il codice sorgente completo e la suite di test unitari con mock.
Le api che si andranno ad utilizzare sono quelle create con la libreria [PHPCrudApi](https://github.com/mevdschee/php-crud-api)

## Installazione

1. **PIP**:
    ```python
    pip install py_client_cap
    ```
## Uso

### 1. Utilizzo della libreria

```python
from py_client_cap import CrudPHPDB

base_url = "http://127.0.0.1:8082/modules/api/index.php"
api_key = "test-token"

db = CrudPHPDB(base_url=base_url, api_key=api_key)

# Ritorna le tabelle
tables = db.list_tables()

# Usa le tabelle
table_client = db.table( 'Tabella1', raise_if_not_found=True)
response_records = table_client.list_rows(page=1,size=1)
records_count = table_client.last_total_count

#Il totale delle tabelle viene restituito solo se la ricerca e' con page=x
```

# Gestire le Tabelle

## Classe CrudPHPTable

La classe `CrudPHPTable` è stata creata per gestire le operazioni su una tabella PHP API. Questa classe estende la classe base `CrudPHPApi` e aggiunge funzionalità per elencare i record, selezionare un singolo record, inserire un nuovo record, aggiornare un record esistente e eliminare un record.

### Costruttore

```python
def __init__(self, base_url: str, table_name: str, api_key: Optional[str] = None, timeout: int = 10):
    """
    Inizializza la classe CrudPHPTable.

    Args:
        base_url (str): URL base del server PHP API.
        table_name (str): Nome della tabella a cui si intende accedere.
        api_key (str, optional): Chiave API per autenticazione. Default è None.
        timeout (int, optional): Timeout per le richieste HTTP. Default è 10.
    """
```

### Metodi

#### `_build_table_endpoint`

```python
def _build_table_endpoint(self, action_path: str = "") -> str:
    """
    Costruisce l'endpoint della tabella.

    Args:
        action_path (str, optional): Percorso di azione specifico. Default è None.

    Returns:
        str: Endpoint della tabella.
    """
```

#### `list_rows`

```python
def list_rows(
    self, 
    filters: Optional[Union[str, List[str]]] = None, 
    logic: str = "and",  # "and" oppure "or"
    order: Optional[Union[str, List[str]]] = None, 
    page: Optional[int] = None, 
    size: Optional[int] = None, 
    query_params: Optional[Dict[str, Any]] = None, 
    headers: Optional[Dict[str, str]] = None
) -> ApiResponse:
    """
    Effettua una richiesta GET per elencare i record della tabella.

    Args:
        filters (Union[str, List[str]], optional): Filtro da applicare alle query. Default è None.
        logic (str, optional): Logica di filtre ("and" o "or"). Default è "and".
        order (Union[str, List[str]], optional): Ordinamento delle risposte. Default è None.
        page (int, optional): Pagina di risposta da ottenere. Default è None.
        size (int, optional): Numero di record per pagina. Default è None.
        query_params (Dict[str, Any], optional): Parametri di query. Default è None.
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

#### `get_row`

```python
def get_row(self, row_id: Any, query_params: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None) -> ApiResponse:
    """
    Effettua una richiesta GET per selezionare un singolo record della tabella.

    Args:
        row_id (Any): Identificatore del record.
        query_params (Dict[str, Any], optional): Parametri di query. Default è None.
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

#### `insert_row`

```python
def insert_row(self, payload: Dict[str, Any], headers: Optional[Dict[str, str]] = None) -> ApiResponse:
    """
    Effettua una richiesta POST per inserire un nuovo record nella tabella.

    Args:
        payload (Dict[str, Any]): Payload del nuovo record.
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

#### `update_row`

```python
def update_row(self, row_id: Any, payload: Dict[str, Any], headers: Optional[Dict[str, str]] = None) -> ApiResponse:
    """
    Effettua una richiesta PUT per aggiornare un record esistente nella tabella.

    Args:
        row_id (Any): Identificatore del record.
        payload (Dict[str, Any]): Payload dell'aggiornamento.
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

#### `delete_row`

```python
def delete_row(self, row_id: Any, headers: Optional[Dict[str, str]] = None) -> ApiResponse:
    """
    Effettua una richiesta DELETE per eliminare un record dalla tabella.

    Args:
        row_id (Any): Identificatore del record.
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

#### `to_class`

```python
def to_class(self, headers: Optional[Dict] = None) -> ApiResponse:
    """
    Effettua una richiesta GET per esportare la struttura della tabella in formato OpenAPI.

    Args:
        headers (Dict[str, str], optional): Header HTTP. Default è None.

    Returns:
        ApiResponse: Risposta della richiesta.
    """
```

### Note

- L'API REST è gestita automaticamente dalla classe `CrudPHPApi`, che estende `requests.Session`.
- Il metodo `_build_table_endpoint` costruisce l'endpoint della tabella.
- I metodi `list_rows`, `get_row`, `insert_row`, `update_row`, `delete_row` effettuano richieste HTTP GET, POST, PUT e DELETE rispettivamente.
- Il metodo `to_class` effettua una richiesta GET per esportare la struttura della tabella in formato OpenAPI.
- L'API REST richiede autenticazione tramite una chiave API se specificata.

## Esempio di utilizzo

```python
# Importazione della classe CrudPHPTable
from py_client_cap import CrudPHPTable

# Configurazione del client
base_url = "http://example.com/api"
api_key = "your_api_key_here"

# Creazione dell'oggetto CrudPHPTable
table_client = CrudPHPTable(base_url=base_url, api_key=api_key)

# Elenco dei record della tabella
response = table_client.list_rows()
print(response)

Questo esempio mostra come utilizzare la classe 'CrudPHPTable' per effettuare operazioni di liste e selezione di record su una tabella PHP API.
