<p align="center">
<a href="https://www.42berlin.de/" target="_blank">
<kbd>
<img src="https://github.com/42Berlin/.github/blob/main/assets/logo-pink.png?raw=true" width="128" alt="42 Berlin logo"/>
</kbd>
</a>
</p>
<p align="center">
<a href="#what-is-this">About</a> | <a href="#key-features">Key Features</a> | <a href="#installation">Installation</a> | <a href="#configuration">Configuration</a> | <a href="#usage">Usage</a> | <a href="#contribute">Contribute</a>
</p>
<p align="center">
<sub>Created by ???</sub
</p>
<p align="center" style="margin: 0; padding: 0; line-height: 1;">↓</p>
<p align="center">
<sub>Adapted by <a href="https://hive.fi">Hive Helsinki</a> for all the 42 Network (the best 🫶🏻)</sub>
</p>
<p align="center" style="margin: 0; padding: 0; line-height: 1;">↓</p>
<p align="center">
<sub>Re-adapted by <a href="https://42berlin.de">42 Berlin</a> to include new API v3 calls, inspired by <a href="https://github.com/maperrea/api42-wrapper/blob/master/api42/api42.py">42api-wrapper</a> from 19 Belgium đź–¤</sub>
</p>
## What is this?
This is a Python script that facilitates making requests to the 42 Network's API. It will do all the hard work such as getting, refreshing, updating tokens and pagination. All you need to do is provide the endpoint from which you want to retrieve data, and this script will take care of the rest.
Example usage:
```python
from api42lib import IntraAPIClient
ic = IntraAPIClient(config_path="./config.yml")
users = ic.pages_threaded("users")
for user in users:
print(user["login"])
freezes = ic.pages_threaded("freeze/v2/freezes")
for freeze in freezes:
print(freeze["id"])
```
This is a fork of the original [42API-Lib](https://github.com/hivehelsinki/42api-lib) made by Hive.
You can explore the API Documentation and available endpoints [here](https://api.intra.42.fr/apidoc).
## Key Features
* **API v2 and v3 Support:** The library is compatible with both API v2 and v3 calls, allowing users to continue using v2 routes while also using the new v3 endpoints. You can use any of the following URL formats to make a request:
```yaml
V2:
- *
- https://api.intra.42.fr/v2/*
- /v2/*
- v2/*
V3:
- pace-system/v1/*
- freeze/v2/*
- v3/pace-system/v1/*
- /v3/pace-system/v1/*
- v3/freeze/v2/*
- /v3/freeze/v2/*
- https://pace-system.42.fr/api/v1/*
- https://freeze.42.fr/api/v2/*
```
* **Token Management:** Tokens are managed internally and requested when the `expires_at` date is reached, avoiding the need to make an initial request to check if the token was valid.
* **Singleton:** The library uses a singleton pattern to ensure that only one instance of the `IntraAPIClient` class is created. This avoids the need to pass the instance around in your code and tokens are shared across all instances.
* **Variable config file path**: The class has a `config_file` parameter that allows you to specify a different configuration file. If you don't provide a file path, the library will look for a `config.yml` file in the current directory.
* **Threads**: Re-worked the `pages_threaded` method. Also the number of threads is dynamically calculated based on available CPUs.
## Installation
We recommend using a virtual environment. We use [Poetry](https://python-poetry.org/) for dependency management, but you can use any other package manager you prefer.
Run the following command to install the package with Poetry:
```bash
poetry add api42lib
```
If you prefer to use pip, you can install the package with the following command:
```bash
pip install api42lib
```
## Configuration
You can copy the sample file and edit it with your api credentials:
```bash
cp config.sample.yml config.yml
```
Here is an overview of the config.yml file:
```yaml
intra:
v2:
client: "" # <- insert your v2 app’s UID here
secret: "" # <- insert your app’s SECRET here
uri: "https://api.intra.42.fr/v2/oauth/token"
endpoint: "https://api.intra.42.fr/v2"
scopes: "public"
v3:
client: "" # <- insert your v3 app’s UID here
secret: "" # <- insert your app’s SECRET here
login: "" # <- insert your intra LOGIN here
password: "" # <- insert your intra PASSWORD here
uri: 'https://auth.42.fr/auth/realms/staff-42/protocol/openid-connect/token'
```
To get the v2 client and secret, you will have to create an app, you can find how by [reading the manual](https://api.intra.42.fr/apidoc/guides/getting_started).
The v3 client and secrets are provided by 42 Central. These calls also require the login and password of a user with the appropriate permissions.
## Usage
You can import the `IntraAPIClient` class and create an instance of it:
```python
from api42lib import IntraAPIClient
ic = IntraAPIClient()
```
If the config.yml is in another path other than the root directory, you can specify it as a parameter:
```python
from api42lib import IntraAPIClient
ic = IntraAPIClient(config_path="path/to/config.yml")
```
The library supports following methods: `GET`, `POST`, `PATCH`, `PUT` and `DELETE`.
The basic app will only be able to use `GET`, for other methods, you will have to take a look at Roles Entities for permissions.
To use the previous methods, you need to provide the specific endpoint. For example:
```python
# For v2 calls
response = ic.get("teams")
response = ic.get("v2/teams")
response = ic.get("/v2/teams")
# For v3 calls
response = ic.get("freeze/v2/freezes")
response = ic.get("v3/freeze/v2/freezes")
response = ic.get("/v3/freeze/v2/freezes")
response = ic.get("pace-system/v1/users")
response = ic.get("v3/pace-system/v1/users")
response = ic.get("/v3/pace-system/v1/users")
```
Or with a full URL:
```python
# For v2 calls
response = ic.get("https://api.intra.42.fr/v2/teams")
# For v3 calls
response = ic.get("https://pace-system.42.fr/api/v1/users")
response = ic.get("https://freeze.42.fr/api/v2/freezes")
```
This example will return a request object.
To work with the response data, you may want to convert it to a json object:
```python
if response.status_code == 200: # Make sure response status is OK
data = response.json()
```
### Parameters:
If (should be when by now) you have read the API documentary, you may have noticed that you can apply all kinds of parameters to the request. These parameters include things like `sort`, `filter` and `range`. Make sure you always check the specific page in the documentation because different endpoints have different parameters and different ways of using them.
Parameters can be used to further specify your request without making the actual request string a mess. They are given as a parameter to the class method and should be in object format. An example of parameters and their usage:
```python
params = {
"filter[primary_campus]": 51,
"filter[cursus]": 21,
"range[final_mark]": "100,125",
"sort":" -final_mark,name"
}
```
Here we are filtering by `campus` and `cursus`, results must be in a specified range of `final_mark` and they must be sorted in descending order based on `final_mark` and ascending order based on `name`.
To use the parameters with a certain request, you simply add them as a keyword argument params:
```python
response = ic.get("teams", params=params)
```
### Pagination:
Most of the endpoints are paginated with the request parameters `page`(both v2 & v3) and `per_page`(only for v2). In order to receive all of the data of a certain endpoint, you usually need to do multiple requests.
* `ic.pages()` retrieves all data from an endpoint, making multiple requests until all data is retrieved.
* `ic.pages_threaded()` does the same thing but in multiple threads, reducing the time it takes to retrieve requests.
Example usage:
```python
userList = ic.pages_threaded("users")
```
Enable a progress bar for lengthy operations (enabled by default):
```python
ic.progress_bar_enable()
```
To disable the progress bar:
```python
ic.progress_bar_disable()
```
## Contribute
Spot an Error? Want to Contribute? Submit a pull request to fix or add features!
To develop your own changes clone this repository, make changes and install the package locally to test it:
```bash
pip install .
```
You can run all tests with pytest (make sure to have pytest installed first):
```bash
pytest
```
Raw data
{
"_id": null,
"home_page": "https://github.com/42Berlin/api42lib",
"name": "api42lib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "api42lib, 42, api, 42api, ft, api, ft-api, 42school, 42-school, 42-school-api, 42-api, 42-lib, 42-library",
"author": "tech42berlin",
"author_email": "tech@42berlin.de",
"download_url": "https://files.pythonhosted.org/packages/d7/d3/54e6ae07853712ce3c31a2faf8bc3d98dcc8bd86753288e02b3ef47f1a31/api42lib-0.1.9.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://www.42berlin.de/\" target=\"_blank\">\n <kbd>\n <img src=\"https://github.com/42Berlin/.github/blob/main/assets/logo-pink.png?raw=true\" width=\"128\" alt=\"42 Berlin logo\"/>\n </kbd>\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#what-is-this\">About</a> | <a href=\"#key-features\">Key Features</a> | <a href=\"#installation\">Installation</a> | <a href=\"#configuration\">Configuration</a> | <a href=\"#usage\">Usage</a> | <a href=\"#contribute\">Contribute</a>\n</p>\n\n<p align=\"center\">\n <sub>Created by ???</sub\n</p>\n\n<p align=\"center\" style=\"margin: 0; padding: 0; line-height: 1;\">↓</p>\n\n<p align=\"center\">\n <sub>Adapted by <a href=\"https://hive.fi\">Hive Helsinki</a> for all the 42 Network (the best \ud83e\udef6\ud83c\udffb)</sub>\n</p>\n\n<p align=\"center\" style=\"margin: 0; padding: 0; line-height: 1;\">↓</p>\n\n<p align=\"center\">\n <sub>Re-adapted by <a href=\"https://42berlin.de\">42 Berlin</a> to include new API v3 calls, inspired by <a href=\"https://github.com/maperrea/api42-wrapper/blob/master/api42/api42.py\">42api-wrapper</a> from 19 Belgium \ud83d\udda4</sub>\n</p>\n\n\n## What is this?\nThis is a Python script that facilitates making requests to the 42 Network's API. It will do all the hard work such as getting, refreshing, updating tokens and pagination. All you need to do is provide the endpoint from which you want to retrieve data, and this script will take care of the rest.\n\nExample usage:\n```python\nfrom api42lib import IntraAPIClient\n\nic = IntraAPIClient(config_path=\"./config.yml\")\n\nusers = ic.pages_threaded(\"users\")\nfor user in users:\n print(user[\"login\"])\n\nfreezes = ic.pages_threaded(\"freeze/v2/freezes\")\nfor freeze in freezes:\n print(freeze[\"id\"])\n```\n\nThis is a fork of the original [42API-Lib](https://github.com/hivehelsinki/42api-lib) made by Hive.\n\nYou can explore the API Documentation and available endpoints [here](https://api.intra.42.fr/apidoc).\n\n## Key Features\n* **API v2 and v3 Support:** The library is compatible with both API v2 and v3 calls, allowing users to continue using v2 routes while also using the new v3 endpoints. You can use any of the following URL formats to make a request:\n ```yaml\n V2:\n - *\n - https://api.intra.42.fr/v2/*\n - /v2/*\n - v2/*\n\n V3:\n - pace-system/v1/*\n - freeze/v2/*\n - v3/pace-system/v1/*\n - /v3/pace-system/v1/*\n - v3/freeze/v2/*\n - /v3/freeze/v2/*\n - https://pace-system.42.fr/api/v1/*\n - https://freeze.42.fr/api/v2/*\n ```\n\n* **Token Management:** Tokens are managed internally and requested when the `expires_at` date is reached, avoiding the need to make an initial request to check if the token was valid.\n\n* **Singleton:** The library uses a singleton pattern to ensure that only one instance of the `IntraAPIClient` class is created. This avoids the need to pass the instance around in your code and tokens are shared across all instances.\n\n* **Variable config file path**: The class has a `config_file` parameter that allows you to specify a different configuration file. If you don't provide a file path, the library will look for a `config.yml` file in the current directory.\n\n* **Threads**: Re-worked the `pages_threaded` method. Also the number of threads is dynamically calculated based on available CPUs.\n\n\n## Installation\nWe recommend using a virtual environment. We use [Poetry](https://python-poetry.org/) for dependency management, but you can use any other package manager you prefer.\n\nRun the following command to install the package with Poetry:\n```bash\npoetry add api42lib\n```\n\nIf you prefer to use pip, you can install the package with the following command:\n```bash\npip install api42lib\n```\n\n\n## Configuration\nYou can copy the sample file and edit it with your api credentials:\n\n```bash\ncp config.sample.yml config.yml\n```\n\nHere is an overview of the config.yml file:\n```yaml\nintra:\n v2:\n client: \"\" # <- insert your v2 app\u2019s UID here\n secret: \"\" # <- insert your app\u2019s SECRET here\n uri: \"https://api.intra.42.fr/v2/oauth/token\"\n endpoint: \"https://api.intra.42.fr/v2\"\n scopes: \"public\"\n v3:\n client: \"\" # <- insert your v3 app\u2019s UID here\n secret: \"\" # <- insert your app\u2019s SECRET here\n login: \"\" # <- insert your intra LOGIN here\n password: \"\" # <- insert your intra PASSWORD here\n uri: 'https://auth.42.fr/auth/realms/staff-42/protocol/openid-connect/token'\n```\n\nTo get the v2 client and secret, you will have to create an app, you can find how by [reading the manual](https://api.intra.42.fr/apidoc/guides/getting_started).\n\nThe v3 client and secrets are provided by 42 Central. These calls also require the login and password of a user with the appropriate permissions.\n\n\n## Usage\nYou can import the `IntraAPIClient` class and create an instance of it:\n```python\nfrom api42lib import IntraAPIClient\n\nic = IntraAPIClient()\n```\n\nIf the config.yml is in another path other than the root directory, you can specify it as a parameter:\n```python\nfrom api42lib import IntraAPIClient\n\nic = IntraAPIClient(config_path=\"path/to/config.yml\")\n```\n\nThe library supports following methods: `GET`, `POST`, `PATCH`, `PUT` and `DELETE`.\nThe basic app will only be able to use `GET`, for other methods, you will have to take a look at Roles Entities for permissions.\n\nTo use the previous methods, you need to provide the specific endpoint. For example:\n```python\n# For v2 calls\nresponse = ic.get(\"teams\")\nresponse = ic.get(\"v2/teams\")\nresponse = ic.get(\"/v2/teams\")\n# For v3 calls\nresponse = ic.get(\"freeze/v2/freezes\")\nresponse = ic.get(\"v3/freeze/v2/freezes\")\nresponse = ic.get(\"/v3/freeze/v2/freezes\")\nresponse = ic.get(\"pace-system/v1/users\")\nresponse = ic.get(\"v3/pace-system/v1/users\")\nresponse = ic.get(\"/v3/pace-system/v1/users\")\n```\n\nOr with a full URL:\n```python\n# For v2 calls\nresponse = ic.get(\"https://api.intra.42.fr/v2/teams\")\n# For v3 calls\nresponse = ic.get(\"https://pace-system.42.fr/api/v1/users\")\nresponse = ic.get(\"https://freeze.42.fr/api/v2/freezes\")\n```\n\nThis example will return a request object.\nTo work with the response data, you may want to convert it to a json object:\n```python\nif response.status_code == 200: # Make sure response status is OK\n data = response.json()\n```\n\n### Parameters:\nIf (should be when by now) you have read the API documentary, you may have noticed that you can apply all kinds of parameters to the request. These parameters include things like `sort`, `filter` and `range`. Make sure you always check the specific page in the documentation because different endpoints have different parameters and different ways of using them.\n\nParameters can be used to further specify your request without making the actual request string a mess. They are given as a parameter to the class method and should be in object format. An example of parameters and their usage:\n```python\nparams = {\n \"filter[primary_campus]\": 51,\n \"filter[cursus]\": 21,\n \"range[final_mark]\": \"100,125\",\n \"sort\":\" -final_mark,name\"\n}\n```\n\nHere we are filtering by `campus` and `cursus`, results must be in a specified range of `final_mark` and they must be sorted in descending order based on `final_mark` and ascending order based on `name`.\n\nTo use the parameters with a certain request, you simply add them as a keyword argument params:\n```python\nresponse = ic.get(\"teams\", params=params)\n```\n\n### Pagination:\nMost of the endpoints are paginated with the request parameters `page`(both v2 & v3) and `per_page`(only for v2). In order to receive all of the data of a certain endpoint, you usually need to do multiple requests.\n\n* `ic.pages()` retrieves all data from an endpoint, making multiple requests until all data is retrieved.\n* `ic.pages_threaded()` does the same thing but in multiple threads, reducing the time it takes to retrieve requests.\n\nExample usage:\n```python\nuserList = ic.pages_threaded(\"users\")\n```\n\nEnable a progress bar for lengthy operations (enabled by default):\n```python\nic.progress_bar_enable()\n```\n\nTo disable the progress bar:\n```python\nic.progress_bar_disable()\n```\n\n## Contribute\nSpot an Error? Want to Contribute? Submit a pull request to fix or add features!\n\nTo develop your own changes clone this repository, make changes and install the package locally to test it:\n```bash\npip install .\n```\n\nYou can run all tests with pytest (make sure to have pytest installed first):\n```bash\npytest\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for interacting with 42.fr API (v2 and v3). Maintained by 42 Berlin.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/42Berlin/api42lib"
},
"split_keywords": [
"api42lib",
" 42",
" api",
" 42api",
" ft",
" api",
" ft-api",
" 42school",
" 42-school",
" 42-school-api",
" 42-api",
" 42-lib",
" 42-library"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b894790d2af3709c326424b7e0f6695a3b2a86f995f76d291f41b3270ad37553",
"md5": "172ab53e2ab894bd4e2bd15d6d3ec6ff",
"sha256": "7980479430604fd66b1677ffe3b87c1a8905d9c7bc8ff01bb453ad908f846bbd"
},
"downloads": -1,
"filename": "api42lib-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "172ab53e2ab894bd4e2bd15d6d3ec6ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11498,
"upload_time": "2024-09-13T15:10:35",
"upload_time_iso_8601": "2024-09-13T15:10:35.363925Z",
"url": "https://files.pythonhosted.org/packages/b8/94/790d2af3709c326424b7e0f6695a3b2a86f995f76d291f41b3270ad37553/api42lib-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d7d354e6ae07853712ce3c31a2faf8bc3d98dcc8bd86753288e02b3ef47f1a31",
"md5": "610fba8496a6b81ff617f32fe3127bc4",
"sha256": "e5a921a8f356d45be37681b62e4edfb37941c2951af680a83447294ba0372a76"
},
"downloads": -1,
"filename": "api42lib-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "610fba8496a6b81ff617f32fe3127bc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15048,
"upload_time": "2024-09-13T15:10:36",
"upload_time_iso_8601": "2024-09-13T15:10:36.939798Z",
"url": "https://files.pythonhosted.org/packages/d7/d3/54e6ae07853712ce3c31a2faf8bc3d98dcc8bd86753288e02b3ef47f1a31/api42lib-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-13 15:10:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "42Berlin",
"github_project": "api42lib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "api42lib"
}
JSON
