f4j6nn3m5x3-bango-serializers 0.0.1
Python package meant to serve as a base for the developers containing all the serializers that Bango uses for integration.
Requires Python: >=3.10,<4.0

# Bango Serializers 

## Table of Contents

<!-- toc -->

- [Introduction](#introduction)
- [Package Overview](#requirements-for-development)
  - [Base Serializers](#base-serializers)
  - [Payments](#payments)
  - [Resale](#resale)
  - [Subscriptions](#subscription)
- [Requirements for Development](#requirements-for-development)
- [Package development](#package-development)
- [Install package from GitLabCI PYPI registry](#install-package-from-gitlabci-pypi-registry)
- [CI](#ci)
  - [Add Instance variable](#add-instance-variable)
  - [pip.conf](#pipconf)
  - [Setup Steps](#setup-steps)
- [Contributing](#contributing)
- [Miscellaneous](#miscellaneous)
  - [IDE Hints](#ide-hints)
  - [Updating the Table of Contents](#updating-the-table-of-contents)


## Introduction
As Bango we've provided a python package meant to serve as a base for the developers containing all the serializers that Bango uses for integration.

The root web page containing all the information about the integration with the Bango platform can be found [at this link](https://developer.bango.com)

We have 3 main groups on which the serializers are spread: Payment, Resale and Subscription.
We've divided the serializers in the same manner except for some special base classes which are used in several places.

In the following section, we will present a quick overview of what serializers can be found in each file.

## Package Overview

### Base Serializers

In this section we've added the most used base for different serializers:

* CamelModel - based on pydantic base model and pyhumps camelize configuration
* CommunicationInformation
* ClientDevice
* Source
* ExtraInformation
* FinanceData
* Type - enum class type
* StatusValues - enum class type
* EntitlementBenefits - enum class type
* CurrencyCode - enum class type

### Payments

[A more in depth presentation for those serializers can be found here](https://developer.bango.com/payment/payment-provider/api-ref/)

We've grouped them under 2 sections: requests and responses.

In here we can find serializers for:

* Identity - Get User Identity
* Transactions -  GET, UPDATE, CREATE 

### Resale

The resale section is divided in 2 main categories: 

#### For Reseller

[Link with more information about Bango Reseller API can be found here](https://developer.bango.com/resale/api-ref/requests/)

It contains various serializers for Entitlement (separated into requests and responses):

* Create, Update, Get - Entitlement
* Entitlement Report
* Suspend, Resume, Cancel, Revoke - Entitlement

#### For Merchants

This category is divided into 2 categories: 

**Merchant Client**

[Link with more information about Bango Merchant Client API can be found here](https://developer.bango.com/resale/merchant-interface/bango-initiated/)

Contains serializers for Entitlements and Check Eligibility

* Create, Patch, Terminate - Entitlement
* Check eligibility

**Merchant Server**

[Link with more information about Bango Merchant Server API can be found here](https://developer.bango.com/resale/merchant-interface/merchant-initiated/)

Contains serializers for Entitlements and Entitlement Report

* Get, Update, Activate, Terminate - Entitlement
* Entitlement Report - Get a list of entitlements for a bangoUserId, matching specific criteria

### Subscription

[Link with more information about Bango Subscription API can be found here](https://developer.bango.com/subscriptions/api-ref/requests/)

Contains serializers for Subscriptions and Plans

* Create, Get, Cancel, Uncancel - Subscription
* Get - Subscription by External Key
* Retrieve - all subscriptions for a Bango User Id
* Create, Get - Plans

## Requirements for Development

The following tools are required for development:

### MacOS

- python (use [pyenv](https://github.com/pyenv/pyenv) or other virtual environment manager to install the required
  version of python)

### Windows

See [WSL Guide](https://bangonet.atlassian.net/l/c/spYa1G1V) for information about setting up WSL.

### Getting Started

#### Setup Steps

1.  Create a virtual environment:

        python -m venv venv

    For more information about the virtual environment created, take a look at [this](https://bangonet.atlassian.net/wiki/spaces/~909965005/pages/2198831713/Python+Virtual+Environment#.gitignore-file) page.

1.  Activate the virtual environment:

        source venv/bin/activate

1.  Install the require dependencies and the development dependencies:

        pip install -r requirements-dev.txt

1.  Install the hooks for `pre-commit`:

        pre-commit install --hook-type pre-commit

**NB:** More detailed information about the tools/structure/logging of the project can be found on
[this](https://bangonet.atlassian.net/wiki/spaces/OB/pages/2995453953/FastAPI+Template+Guide) page.

### Upgrading Python

When upgrading to another version of Python, follow the below steps:

1. Remove the existing virtual env: `rm -rf venv`
1. Make sure your desired version of Python is in your path: `python -V`
1. Recreate and install the required packages: see [Setup Steps](#setup-steps)

## Package development

### Build package

To take advantage from template:
1. Familiarize with poetry documentation
   - https://python-poetry.org/docs/pyproject/#packages
   - https://python-poetry.org/docs/managing-dependencies/
2. Change `changemyname` in `package-template/package` directory or replace with package application to package
3. Update pyproject.toml `[tool.poetry]` `changemyname` preforms for package name and path
4. Fill pyproject.toml poetry dependencies  (requirements) section:  
   - `[tool.poetry.dependencies]` adding all base python dependencies
   - `[tool.poetry.group.dev.dependencies]` adding all dev python dependencies
   - `[tool.poetry.group.test.dependencies]` adding all test python dependencies
5. Start development:
   - install poetry `pip install poetry`
   - install dependencies `poetry install`
6. Build package:
   - build python package `poetry build` to path {srcdir}/dist
7. Add tests for package to `tests` dir 
8. Optional - Publish package to gitlab packages registry:
   - `TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${API_VERSION}/projects/${PROJECT_ID}/packages/pypi dist/*`

### Testing

#### Running Tests

To run tests with no coverage report and to exit on the first failure:

    python -m pytest --no-cov -x

### Formatting, Linting and Type Checking

#### Formatting

This project is formatted using [black](https://github.com/psf/black). To run formatting
checks manually, run:

    black .

#### Linting

This project is linted using [pylint](http://pylint.pycqa.org/en/stable/) and [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide).
All pylint rules need to pass for the CI/CD pipeline to progress while wemake is currently only
optional; it is however recommended to have both linting tools pass. To manually run pylint:

    pylint app

To manually run flake8:

    flake8

### Updating Dependencies
doc: https://python-poetry.org/docs/cli/#update  
To update all the project's dependencies to their latest **minor** version you can run (from the
root directory):

    poetry update

Poetry will manage updating packages to latest versions without dependencies conflicts 

## Install package from GitLabCI PYPI registry

> package requires python 3.10 or newer.
> To manage multiple python version check [pyenv](https://github.com/pyenv/pyenv)

Create `venv` in project directory.

```bash
python -m venv venv # create python venv
. venv/bin/activate # activate venv
```

Create `pip.conf` for `Mac or Linux` or `pip.ini` for `Windows` in your project `venv` directory with following content:

```bash
[global]
index-url = https://pypi.org/simple
trusted-host = gitlab.com
               pypi.org
extra-index-url = https://gitlab.com/api/v4/projects/42032165/packages/pypi/simple
```
You can check default directories using `pip config list -v` by default for python `venv` pip will search for `$VIRTUAL_ENV/pip.conf`

Example for Ubuntu:
```bash
user@DMC:~/package-template$ pip config list -v
For variant 'global', will try loading '/etc/xdg/pip/pip.conf'
For variant 'global', will try loading '/etc/pip.conf'
For variant 'user', will try loading '/home/user/.pip/pip.conf'
For variant 'user', will try loading '/home/user/.config/pip/pip.conf'
For variant 'site', will try loading '/home/user/repo/package/venv/pip.conf'
global.extra-index-url='https://gitlab.com/api/v4/projects/42032165/packages/pypi/simple'
global.index-url='https://pypi.org/simple'
global.trusted-host='gitlab.com\npypi.org'
```


[Learn more about pip.conf](https://pip.pypa.io/en/stable/topics/configuration/?highlight=pip.ini)


Create `~/.netrc` file in your home directory to save you credential to gitlab:

```bash
machine gitlab.com
login __token__
password <insert-token-here>
```
> Why `~/.netrc`? Because pip uses requests under the hood, and request uses `~/.netrc` to authenticate.

Get Personal Access Token:

Go to: [personal_access_tokens](https://gitlab.com/-/profile/personal_access_tokens)

Select scopes [api_read], and paste token to `<insert-token-here>` in `~/.netrc` file.

Set the permissions on `~/.netrc` so that only you can view or modify it. For example, on Linux or macOS, run:

```bash
chown $USER ~/.netrc
chmod 0600 ~/.netrc
```

Install module:

1. Inline:

      ```bash
      pip install bango-serializers
      ```

      or

      ```bash
      pip install bango-serializers --index-url https://gitlab.com/api/v4/groups/42032165/-/packages/pypi/simple
      ```

2. Using requirements.txt

      Content of `requirements.txt`:
      ```bash
      --extra-index-url https://gitlab.com/api/v4/projects/42032165/packages/pypi/simple
      my-package-name-here
      ```
      Install using `requirements.txt`:
      ```bash
      pip install -r example/requirements.txt
      ```

## CI
For projects cloned from FastAPI Template that require package we need to add `pip.conf` and set `Instance Variable`.

### Add Instance variable
>  To add an instance variable:<br>
>  On the top bar, select `Main menu > Admin`.<br>
>  On the left sidebar, select `Settings > CI/CD` and expand the `Variables` section.<br>

>  Select Add variable and fill in the details:<br>
>      Key: `CI_BANGO_PY_MODULES`<br>
>      Value: `True`<br>
>      Type: `Variable`.<br>
>      Protect variable: untick<br>
>      Mask variable: untick<br>

This variable switch CI pipeline to build docker image with credentials, so we're able to fetch bango-serializer (CI_GITLAB_PY_MODULES_API_USERNAME / CI_GITLAB_PY_MODULES_API_TOKEN)

### pip.conf
`pip.conf` sets `extra-index-url` for private package and `index-url` for public one

```ini
[global]
index-url = https://pypi.org/simple
trusted-host = gitlab.com
               pypi.org
# extra-index for bango-serializers
extra-index-url = https://${CI_GITLAB_PY_MODULES_API_USERNAME}:${CI_GITLAB_PY_MODULES_API_TOKEN}@gitlab.com/api/v4/projects/42032165/packages/pypi/simple
```

`${CI_GITLAB_PY_MODULES_API_USERNAME}` and `${CI_GITLAB_PY_MODULES_API_TOKEN}` variables are substituted by CI and at the end pip.conf is removed.
### Setup Steps

1. Install the required dependencies and the development dependencies:

        pip install -r requirements.txt

2. Install the hooks for `pre-commit`:

        pre-commit install --hook-type pre-commit


## Contributing

Whilst contributing to the project, take note of the commit message [format](https://bangonet.atlassian.net/wiki/spaces/AWS/pages/904036535/Commit+Messages+and+Tagging+Guidelines)
required. A pre-receive hook will check commit messages and prevent you from pushing if they are
not in the correct format.

## Miscellaneous

### IDE Hints

#### VScode settings

To aid testing and debugging from vscode, the following settings are helpful (`.vscode/settings.json`):

```json
{
  "python.testing.cwd": "${workspaceFolder}",
  "python.linting.pylintEnabled": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests", "--no-cov", "-vvv"],
  "python.testing.unittestEnabled": false
}
```

### Updating the Table of Contents

To update the table of contents after adding things to this README you can use
[md-toc](https://pypi.org/project/md-toc/):

    md_toc -p -s 1 gitlab README.md