Skip to main content

A versatile microsimulation free software

Project description

OpenFisca Core

PyPi Downloads PyPi Version Conda Downloads Conda Version

Python Contributors

Newsletter Twitter Slack

OpenFisca is a versatile microsimulation free software. Check the online documentation for more details.

This package contains the core features of OpenFisca, which are meant to be used by country packages such as OpenFisca-France. Bootstrapping your own country package should not take more than 5 minutes: check our country package template.

Environment

OpenFisca runs on Python 3.7. More recent versions should work but are not tested.

OpenFisca also relies strongly on NumPy. The last four minor versions should work, but only the latest/stable is tested.

Installation

If you're developing your own country package, you don't need to explicitly install OpenFisca-Core. It just needs to appear in your package dependencies. If you want to contribute to OpenFisca-Core itself, welcome! To install it locally you can use one of these two options:

  • conda package manager that we recommend for Windows operating system users,
  • or standard Python pip package manager.

Installing openfisca-core with pip

This installation requires Python 3.7+ and GIT installations.

To install openfisca-core locally in development mode run the following commands in a shell terminal:

git clone https://github.com/openfisca/openfisca-core.git
cd openfisca-core
python3 -m venv .venv
source .venv/bin/activate
make install-deps install-edit

Installing openfisca-core with conda

Since openfisca-core version 35.7.7, you could use conda to install OpenFisca-Core.

Conda is the easiest way to use OpenFisca under Windows as by installing Anaconda you will get:

If you are familiar with the command line you could use Miniconda, which needs very much less disk space than Anaconda.

After installing conda, run these commands in an Anaconda Powershell Prompt:

  • conda create --name openfisca python=3.7 to create an openfisca environment.
  • conda activate openfisca to use your new environment.

Then, choose one of the following options according to your use case:

  • conda install -c conda-forge openfisca-core for default dependencies,
  • or conda install -c conda-forge openfisca-core-api if you want the Web API part,
  • or conda install -c conda-forge -c openfisca openfisca-core-dev if you want all the dependencies needed to contribute to the project.

For information on how we publish to conda-forge, see openfisca-core-feedstock.

Testing

Install the test dependencies:

make install-deps install-edit install-test

For integration testing purposes, openfisca-core relies on country-template and extension-template. Because these packages rely at the same time on openfisca-core, they need to be installed separately.

To run the entire test suite:

make test

To run all the tests defined on a test file:

pytest tests/core/test_parameters.py

To run a single test:

pytest tests/core/test_parameters.py -k test_parameter_for_period

Types

This repository relies on MyPy for optional dynamic & static type checking.

As NumPy introduced the typing module in 1.20.0, to ensure type hints do not break the code at runtime, we run the checker against the last four minor NumPy versions.

Type checking is already run with make test. To run the type checker alone:

make check-types

Style

This repository adheres to a certain coding style, and we invite you to follow it for your contributions to be integrated promptly.

Style checking is already run with make test. To run the style checker alone:

make check-style

To automatically style-format your code changes:

make format-style

To automatically style-format your code changes each time you commit:

touch .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

tee -a .git/hooks/pre-commit << END
#!/bin/sh
#
# Automatically format your code before committing.
exec make format-style
END

Documentation

OpenFisca’s toolchain checks whether documentation builds correctly and updates it automatically with each contribution to this repository.

In the meantime, please take a look at our contributing guidelines for some general tips on how to document your contributions, and at our official documentation's repository to in case you want to know how to build it by yourself —and improve it!

Serving the API

OpenFisca-Core provides a Web-API. It is by default served on the 5000 port.

To run it with the mock country package openfisca_country_template and another port value such as 2000, run:

openfisca serve --country-package openfisca_country_template --port 2000

To read more about the openfisca serve command, check out its documentation.

By default, the Web API uses 3 workers to avoid this issue. Without it, AJAX requests from Chrome sometimes take more than 20s to process. You can change the number of workers by specifying a --workers k option.

You can test that the API is running by executing the command:

curl http://localhost:2000/parameters

For more information about endpoints and input formatting, see the official documentation.

Tracker

The OpenFisca Web API comes with an optional tracker which allows you to measure the usage of the API.

Tracker installation

The tracker is not installed by default. To install it, run:

pip install openfisca_core[tracker] --use-deprecated=legacy-resolver # Or `pip install --editable ".[tracker]"` for an editable installation

Tracker configuration

The tracker is activated when these two options are set:

  • --tracker-url: An URL ending with piwik.php. It defines the Piwik instance that will receive the tracking information. To use the main OpenFisca Piwik instance, use https://stats.data.gouv.fr/piwik.php.
  • --tracker-idsite: An integer. It defines the identifier of the tracked site on your Piwik instance. To use the main OpenFisca piwik instance, use 4.
  • --tracker-token: A string. It defines the Piwik API Authentication token to differentiate API calls based on the user IP. Otherwise, all API calls will seem to come from your server. The Piwik API Authentication token can be found in your Piwik interface when you are logged in.

For instance, to run the Web API with the mock country package openfisca_country_template and the tracker activated, run:

openfisca serve --country-package openfisca_country_template --port 5000 --tracker-url https://stats.data.gouv.fr/piwik.php --tracker-idsite 4 --tracker-token $TRACKER_TOKEN

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openfisca_core-43.3.8.tar.gz (199.0 kB view details)

Uploaded Source

Built Distribution

openfisca_core-43.3.8-py3-none-any.whl (259.3 kB view details)

Uploaded Python 3

File details

Details for the file openfisca_core-43.3.8.tar.gz.

File metadata

  • Download URL: openfisca_core-43.3.8.tar.gz
  • Upload date:
  • Size: 199.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.13

File hashes

Hashes for openfisca_core-43.3.8.tar.gz
Algorithm Hash digest
SHA256 fb6628ce121b3d4138bb387e746dcccf2d9cf1c318cbb10d6e4eca0afc89b37b
MD5 5474038df666f71c16d107554b89ec26
BLAKE2b-256 837f1957ad6b19a5d66401957c69c6cca5e57be319174c8dd5aebf1196bffc9d

See more details on using hashes here.

File details

Details for the file openfisca_core-43.3.8-py3-none-any.whl.

File metadata

File hashes

Hashes for openfisca_core-43.3.8-py3-none-any.whl
Algorithm Hash digest
SHA256 c3f58622779d8ec734f5272c99308010d1ebbc3bc4325d112912fb49d07233fd
MD5 1ea646d7ac80977b054f6d0f2caa4734
BLAKE2b-256 072ee82f8a2162001c5c3e4e5bd94793221ac6a135ce51a5b6ba794c52f04746

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page