Metadata-Version: 2.4
Name: grimoirelab-toolkit
Version: 1.2.5
Summary: Toolkit of common functions used across GrimoireLab
License: GPL-3.0+
License-File: AUTHORS
License-File: LICENSE
Keywords: development,grimoirelab
Author: GrimoireLab Developers
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Project-URL: Homepage, https://chaoss.github.io/grimoirelab/
Project-URL: Repository, https://github.com/chaoss/grimoirelab-toolkit
Description-Content-Type: text/markdown

# GrimoireLab Toolkit [![Build Status](https://github.com/chaoss/grimoirelab-toolkit/workflows/tests/badge.svg)](https://github.com/chaoss/grimoirelab-toolkit/actions?query=workflow:tests+branch:main+event:push) [![Coverage Status](https://img.shields.io/coveralls/chaoss/grimoirelab-toolkit.svg)](https://coveralls.io/r/chaoss/grimoirelab-toolkit?branch=main)

Toolkit of common functions used across GrimoireLab projects.

This package provides a library composed by functions widely used in other
GrimoireLab projects. These function deal with date handling, introspection,
URIs/URLs, among other topics.

## Requirements

 * Python >= 3.8

You will also need some other libraries for running the tool, you can find the
whole list of dependencies in [pyproject.toml](pyproject.toml) file.

## Installation

There are several ways to install GrimoireLab Toolkit on your system: packages or source 
code using Poetry or pip.

### PyPI

GrimoireLab Toolkit can be installed using pip, a tool for installing Python packages. 
To do it, run the next command:
```
$ pip install grimoirelab-toolkit
```

### Source code

To install from the source code you will need to clone the repository first:
```
$ git clone https://github.com/chaoss/grimoirelab-toolkit
$ cd grimoirelab-toolkit
```

Then use pip or Poetry to install the package along with its dependencies.

#### Pip
To install the package from local directory run the following command:
```
$ pip install .
```
In case you are a developer, you should install GrimoireLab Toolkit in editable mode:
```
$ pip install -e .
```

#### Poetry
We use [poetry](https://python-poetry.org/) for dependency management and 
packaging. You can install it following its [documentation](https://python-poetry.org/docs/#installation).
Once you have installed it, you can install GrimoireLab Toolkit and the dependencies in 
a project isolated environment using:
```
$ poetry install
```
To spaw a new shell within the virtual environment use:
```
$ poetry shell
```

## Credential Manager Library

This is a module made to retrieve credentials from different secrets management systems like Bitwarden.
It accesses the secrets management service, looks for the desired credential and returns it in String form.

To use the module in your python code

### Bitwarden

```
from grimoirelab_toolkit.credential_manager import BitwardenManager


# Instantiate the Bitwarden manager using the api credentials for login
bw_manager = BitwardenManager("your_client_id", "your_client_secret", "your_master_password")

# Login
bw_manager.login()

# Retrieve a secret from Bitwarden
username = bw_manager.get_secret("github")
password = bw_manager.get_secret("elasticsearch")

# Logout
bw_manager.logout()
```


#### Response format

When calling `get_secret(item_name)`, the method returns a JSON object with the following structure:

_NOTE: the parameter "item_name" corresponds with the field "name" of the json. That's the name of the item._
(in this case, GitHub)


##### Example Response

  ```json
  {
    "passwordHistory": [
      {
        "lastUsedDate": "2024-11-05T10:27:18.411Z",
        "password": "previous_password_value_1"
      },
      {
        "lastUsedDate": "2024-11-05T09:20:06.512Z",
        "password": "previous_password_value_2"
      }
    ],
    "revisionDate": "2025-05-11T14:40:19.456Z",
    "creationDate": "2024-10-30T18:56:41.023Z",
    "object": "item",
    "id": "91300380-620f-4707-8de1-b21901383315",
    "organizationId": null,
    "folderId": null,
    "type": 1,
    "reprompt": 0,
    "name": "GitHub",
    "notes": null,
    "favorite": false,
    "fields": [
      {
        "name": "api-token",
        "value": "TOKEN"
        "type": 0,
        "linkedId": null
      },
      {
        "name": "api_key",
        "value": "APIKEY",
        "type": 0,
        "linkedId": null
      }
    ],
    "login": {
      "uris": [],
      "username": "your_username",
      "password": "your_password",
      "totp": null,
      "passwordRevisionDate": "2024-11-05T10:27:18.411Z"
    },
    "collectionIds": [],
    "attachments": []
  }
```

  Field Descriptions

  - passwordHistory: Array of previously used passwords with timestamps
  - revisionDate: Last modification timestamp (ISO 8601 format)
  - creationDate: Item creation timestamp (ISO 8601 format)
  - object: Always "item" for credential items
  - id: Unique identifier for this item
  - organizationId: Organization ID if shared, null for personal items
  - folderId: Folder ID if organized, null otherwise
  - type: Item type (1 = login, 2 = secure note, 3 = card, 4 = identity)
  - name: Display name of the credential item (name used as argument in get_secret())
  - notes: Optional notes field
  - favorite: Boolean indicating if item is favorited
  - fields: Array of custom fields with name-value pairs
    - name: Field name
    - value: Field value (can contain secrets)
    - type: Field type (0 = text, 1 = hidden, 2 = boolean)
  - login: Login credentials object
    - username: Login username
    - password: Login password
    - totp: TOTP secret for 2FA (if configured)
    - uris: Array of associated URIs/URLs
    - passwordRevisionDate: Last password change timestamp
  - collectionIds: Array of collection IDs this item belongs to
  - attachments: Array of file attachments

The module uses the [Bitwarden CLI](https://bitwarden.com/help/cli/) to interact with Bitwarden.

## License

Licensed under GNU General Public License (GPL), version 3 or later.

