Skip to main content

42 Berlin logo

About  |  Key Features  |  Installation  |  Configuration  |  Usage  |  Contribute

Created by ???

↓

Adapted by Hive Helsinki for all the 42 Network (the best 🫶🏻)

↓

Re-adapted by 42 Berlin to include new API v3 calls, inspired by 42api-wrapper from 19 Belgium 🖤

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:

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 made by Hive.

You can explore the API Documentation and available endpoints here.

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:

    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 UV for dependency management, but you can use any other package manager you prefer.

Run the following command to install the package with UV:

uv add api42lib

If you prefer to use pip, you can install the package with the following command:

pip install api42lib

Configuration

You can copy the sample file and edit it with your api credentials:

cp config.sample.yml config.yml

Here is an overview of the config.yml file:

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.

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:

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:

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:

# 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:

# 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:

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:

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:

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:

userList = ic.pages_threaded("users")

Enable a progress bar for lengthy operations (enabled by default):

ic.progress_bar_enable()

To disable the progress bar:

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:

uv sync --dev

You can run all tests with pytest (make sure to have pytest installed first):

uv run pytest

Metadata

Release files for api42lib 0.1.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for api42lib 0.1.10
File Size Uploaded Provenance Actions
api42lib-0.1.10.tar.gz 15.9 kB Without provenance Details for api42lib-0.1.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for api42lib 0.1.10
File Interpreter ABI Platform Actions
api42lib-0.1.10-py3-none-any.whl Python 3 none any Details for api42lib-0.1.10-py3-none-any.whl

Total release size: 27.8 kB

Release files / api42lib-0.1.10.tar.gz

Download URL api42lib-0.1.10.tar.gz
Size 15.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5104dd9c62606fd555a883ce14a6469237f8d8c3510d781181e4672ebf91dac6
BLAKE2b-256 checksum
How to use checksums
5fdb56ccc395fdfeacd83f4a4e2567c47e5fad3bb2f638250fa6095eab598baf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.2

Release files / api42lib-0.1.10-py3-none-any.whl

Download URL api42lib-0.1.10-py3-none-any.whl
Size 11.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8706f65fdc09fbfb234d1ebcf92d38a229524957164d0ad6eecb41224bf03f0
BLAKE2b-256 checksum
How to use checksums
07b5fe2d34130e461e321a416b0c6b7dadef1e8f54448dd90f06470c08253cdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.2

Security for api42lib 0.1.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page