diff --git a/source/installation/access-countrys-source-code.md b/source/installation/access-countrys-source-code.md new file mode 100644 index 00000000..64ea691e --- /dev/null +++ b/source/installation/access-countrys-source-code.md @@ -0,0 +1,21 @@ +# Access a country's source code + +This section provides instructions to run or modify the [source code](https://github.com/openfisca/country-template) of the `OpenFisca-Country-Template` package. + +These instructions should be able to be followed for any OpenFisca country package, just substitute the `OpenFisca-Country-Template` package with the relevant OpenFisca country package. + +OpenFisca runs with [Python](https://www.python.org/). Its source code is managed with the [Git](https://git-scm.com) version control software. The following steps call the [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation and a `git` command. To check their installation or install them, follow the [Installation requirements](installation-requirements.md) section. + +The `OpenFisca-Country-Template` installation instructions are in its `README` [Advanced installation](https://github.com/openfisca/country-template#b-advanced-installation-git-clone) section. + +> 💡 Other OpenFisca models have their own documentation. Check the existing repositories list on the [Available Packages](https://openfisca.org/en/packages/) section of the openfisca.org website. + +## Testing changes on "ready to use" situations + +Generally when making changes to legislation, there is a need to test the changes with a situation that works with the country's tax and benefit system. + +Sometimes, these situations can be quite complicated to model. Instead of rewriting them everytime, they can be packaged in different formats: + +* As [YAML tests](./../coding-the-legislation/writing_yaml_tests.md) when the output result should be registered. +* As [JSON requests](./../openfisca-web-api/input-output-data.md#describing-the-situation) when the output isn't being tested. Refer to [these examples](https://github.com/openfisca/country-template/tree/main/openfisca_country_template/situation_examples) in the `OpenFisca-Country-Template` repository. These can be adapted as requests to be sent to the OpenFisca web API. +* As [CSV or other data formats](./../simulate/run-simulation.md#data) when there is a large number of situations to save. diff --git a/source/installation/call-existing-web-api.md b/source/installation/call-existing-web-api.md new file mode 100644 index 00000000..a277e3b3 --- /dev/null +++ b/source/installation/call-existing-web-api.md @@ -0,0 +1,13 @@ +# Call an existing web API + +There is a demonstration of the `OpenFisca-Country-Template` web API hosted by OpenFisca community. It is available for testing and interacting with its web API endpoints through [this swagger interface](https://legislation.demo.openfisca.org/swagger). As with all OpenFisca country web API's it does not require installing anything to access it. + +For further information on the possible requests, [this section of the documentation](./../openfisca-web-api/endpoints.md) describes OpenFisca web APIs endpoints. + +> 💡 Other OpenFisca models might have their own hosted web APIs. When looking for an already hosted web API of a specific country package, it is recommended to check the terms of use and contact the maintaining team. + +The `OpenFisca-Country-Template` demonstration API provides examples of the endpoints that are available with all OpenFisca packages. To develop an application that requires calculations specific to a country, that country's OpenFisca web API will be required to access the variables and calculations specific to that country. + +It is advised to host specific OpenFisca instances per application as changes to laws can often require application changes. This will give maintainers the ability to migrate the application to the latest version of a country package in their own timeframes. + +Read [Install a country web API](./install-country-web-api.md) for more information. diff --git a/source/installation/call-hosted-web-api.md b/source/installation/call-hosted-web-api.md deleted file mode 100644 index 5eb6829c..00000000 --- a/source/installation/call-hosted-web-api.md +++ /dev/null @@ -1,10 +0,0 @@ -# Call a public web API - -You can rely on a demonstration instance for the `OpenFisca-Country-Template` web API hosted by OpenFisca community. You can test it and interact with this web API endpoints through [this swagger interface](https://legislation.demo.openfisca.org/swagger). - -For further information on the possible requests, [this section of the documentation](./../openfisca-web-api/endpoints.md) describes OpenFisca web APIs endpoints. - -> 💡 Other OpenFisca models might have their own hosted web APIs. If you are looking for an already hosted instance for a specific country package, we recommend you to check the terms of use and contact the maintaining team. - -Later, before pushing your web application in production, we advise you to host your own instance as service uptime is not garanteed by the `OpenFisca-Country-Template` demonstration instance. Besides, this will allow you to choose when you need to migrate the main revision of the country package served by the web API. -The [Install the country package web API](./install-openfisca-web-api.md) is here to help you! diff --git a/source/installation/index.md b/source/installation/index.md index 453465c8..08e48583 100644 --- a/source/installation/index.md +++ b/source/installation/index.md @@ -1,34 +1,59 @@ -# Get started +# Getting started ```eval_rst .. toctree:: :hidden: - presets - call-hosted-web-api - run-web-no-local-install - install-wheel - install-openfisca-country-template - install-openfisca-web-api - install-with-docker - windows-no-admin - offline-environment +call-existing-web-api +installation-requirements +install-country-web-api +install-country-package +python-api-browser +access-countrys-source-code +install-with-docker +offline-environment +windows-no-admin ``` -This section guides you in installing the [`OpenFisca-Country-Template`](https://github.com/openfisca/country-template) country package as a generic example of an OpenFisca country package. This will also allow you to run the documentation examples on your local environment. +This section is a guide to the various methods of accessing or installing OpenFisca. Follow the guide below to establish what the use case is and get directed to the appropriate section(s). -This model is fictitious and for your project, you will obviously want to work with one that models the set of rules of an actual jurisdiction. We advise you to refer to your target country package repository documentation for specific instructions. Nevertheless, the steps for installing should be similar for every package. +## 1) Identify the country package -If you are working on a web application or would like to test the web API online: -* No installation is needed if you [call a public instance](./call-hosted-web-api.md) of the web API. -* [Install the country package web API](./install-openfisca-web-api.md) to operate your own web API instance with no usage limitations or to send requests with private data, . +The most common approach involves a specific country or jurisdiction package and so in this scenario it's important to identify if that package exists and then continue to step 2 _"Clarify use case"_. +If the goal is contributing to OpenFisca directly (such as this documentation); have a look at the [Contribute](/contribute/index.md) section of this site and also the [OpenFisca Github repositories](https://github.com/openfisca/). -If you want to use an OpenFisca country package without editing the model rules: -* The fastest is to [load the country package on a web hosted Python runtime](./run-web-no-local-install.md). -* To call calculations from your machine, you can [install the country package on your local environment](./install-wheel.md). +## 2) Clarify use case -If you want to both, use and contribute to the rules of a country package, [install it in editable mode](./install-openfisca-country-template.md). +With a specific country or jurisdiction package in mind; ask whether the use case requires [contributions to the rules](index.md#contributing-to-the-rules), or intends to just [utilise existing rules](index.md#utilising-existing-rules) (for example: run simulations). -Finally, some edge cases has been identified by the OpenFisca community. Here is some additional documentation to help you: -* If you need to [install OpenFisca on a Windows machine without administrative rights](./windows-no-admin.md). -* If you need to [install OpenFisca on a server without internet access](./offline-environment.md). +### Utilising existing rules + +If the goal is just to utilise existing rules (rather than contributing to the rules) then consider the following options. + +#### Web API + +Best for online web applications. The two options are: + +* If it exists, [call an existing web API](./call-existing-web-api.md) for your country (no installation necessarily), or +* [Install a country web API](./install-country-web-api.md) to operate your own web API with no usage limitations (see also [Install with Docker](./install-with-docker.md)). + +#### Python API + +Suitable for "desktop" processing and running large simulations: + +* [Install a country package](./install-country-package.md) in a local environment (see also [Install with Docker](./install-with-docker.md)). +* Alternatively, access the [Python API in the browser](./python-api-browser.md). + +### Contributing to the rules + +If the goal includes contributing to the rules of a country package: + +* when it already exists, [access a country's source code](./access-countrys-source-code.md). +* otherwise [bootstrap a new country package](/coding-the-legislation/bootstrapping_a_new_country_package.md) + +## Edge cases + +Finally, some specific edge cases have been described by the OpenFisca community as follows: + +* Installing a specific country OpenFisca package in an [offline environment](./offline-environment.md). +* Installing a specific country OpenFisca package on a [Windows machine without administrative rights](./windows-no-admin.md). diff --git a/source/installation/install-country-package.md b/source/installation/install-country-package.md new file mode 100644 index 00000000..db8e37b4 --- /dev/null +++ b/source/installation/install-country-package.md @@ -0,0 +1,27 @@ +# Install a country package + +This section is a guide on how to install the `OpenFisca-Country-Template` [packaged library](https://pypi.org/project/OpenFisca-Country-Template/). + +These instructions should be able to be followed for any OpenFisca country package that has published their package on [https://pypi.org/](https://pypi.org/) + +It's the minimal installation required to run a country package without the intention of contributing to it. If the use case also requires contributing to the model, please follow the [access a country's source code](./access-countrys-source-code.md) section. + +## Install OpenFisca-Country-Template packaged library + +OpenFisca runs with [Python](https://www.python.org/). The following steps call [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation. To check its installation or install it, first check the [Installation requirements](installation-requirements.md). + +> When other Python projects exist in the intended environment, it is recommended to create a new virtual environment to avoid dependency conflicts. [Here is more information](https://github.com/openfisca/country-template#setting-up-a-virtual-environment-with-venv) from `OpenFisca-Country-Template` documentation. + +To install the latest OpenFisca-Country-Template [published revision](https://pypi.org/project/OpenFisca-Country-Template/#history), run the following command in the environment's terminal: + +```shell +pip install OpenFisca-Country-Template +``` + +It should complete without any errors. To check the installed packages run the following command: + +```shell +pip list +``` + +`OpenFisca-Country-Template` should be in the list indicating that it is installed and ready to run simulations. diff --git a/source/installation/install-country-web-api.md b/source/installation/install-country-web-api.md new file mode 100644 index 00000000..16a2b9d8 --- /dev/null +++ b/source/installation/install-country-web-api.md @@ -0,0 +1,13 @@ +# Install a country web API + +These instructions are for installing an OpenFisca country package in a local environment. The `OpenFisca-Country-Template` package is used as an example here and should be substituted for the specific country package relevant to the use case. + +## Run and call a local web API + +OpenFisca runs with [Python](https://www.python.org/). If it's not installed in the environment, check the [Installation requirements](installation-requirements.md#install-python) section. + +To run a local `OpenFisca-Country-Template` web API: + +1. Install the `OpenFisca-Country-Template` in the local environment as described by it's `README` [Install Instructions for Users and Contributors](https://github.com/openfisca/country-template#install-instructions-for-users-and-contributors) section, + +2. Serve the web API on your environment by running the one command described [here](https://github.com/openfisca/country-template#serve-this-country-package-with-the-openfisca-web-api). diff --git a/source/installation/install-openfisca-country-template.md b/source/installation/install-openfisca-country-template.md deleted file mode 100644 index 95d8a85b..00000000 --- a/source/installation/install-openfisca-country-template.md +++ /dev/null @@ -1,19 +0,0 @@ -# Install and edit the country package - -This section will allow you to install, run or modify the [source code of OpenFisca-Country-Template](https://github.com/openfisca/country-template) model. - -OpenFisca runs with [Python](https://www.python.org/). Its source code is managed through [Git](https://git-scm.com) version control system. So, the following steps call [pip package installer](https://pypi.org/project/pip/) that requires a `Python` installation and `git` command. To check their installation or install them, the [presets page](presets.md) is here for you! - -Then you will find the `OpenFisca-Country-Template` installation instruction in its `README` [Advanced installation](https://github.com/openfisca/country-template#b-advanced-installation-git-clone) section. - -> 💡 Other OpenFisca models have their own documentation. You will find the existing repositories list on [this page of openfisca.org](https://openfisca.org/en/countries/) website. - -## How to test your changes on "ready to use" situations - -Often, when making changes to legislation, you need to test it on a situation that works with your country's tax and benefit system. - -Sometimes, these situations can be quite complicated to model (such as roomates). Instead of re-writing them everytime, they could be packaged in different formats: - -* As [YAML tests](./../coding-the-legislation/writing_yaml_tests.md) when the output result should be registered. -* As [JSON request](./../openfisca-web-api/input-output-data.md#describing-the-situation) when the question sent to openfisca is the only thing to register. As an example, we have pre-packaged a few for `OpenFisca-France` in a Python Package.You can find the package along with a usage example in the [Tutorial repository](https://github.com/openfisca/tutorial/tree/master/python/scripts/generate_situation_examples). -* As [CSV or other data formats](./../simulate/run-simulation.md#data) when there is a large number of situations to save. diff --git a/source/installation/install-openfisca-web-api.md b/source/installation/install-openfisca-web-api.md deleted file mode 100644 index 66048005..00000000 --- a/source/installation/install-openfisca-web-api.md +++ /dev/null @@ -1,13 +0,0 @@ -# Install the country package web API - -You can call `OpenFisca-Country-Template` web API without installing it by [relying on the demonstration instance](./call-hosted-web-api.md). Or install it on your local environment for further testing by following this section. - -## Run and call a local instance - -OpenFisca runs with [Python](https://www.python.org/). If it's not installed on your environment, the [presets Python install section](presets.md#install-python) is here for you! - -To run a local instance of `OpenFisca-Country-Template` web API, you need to: - -1. Install `OpenFisca-Country-Template` on your local environment as described by its `README` [Install Instructions for Users and Contributors](https://github.com/openfisca/country-template#install-instructions-for-users-and-contributors) section, - -2. Serve the web API on your environment by running one command as described [here](https://github.com/openfisca/country-template#serve-this-country-package-with-the-openfisca-web-api). diff --git a/source/installation/install-wheel.md b/source/installation/install-wheel.md deleted file mode 100644 index d3cc5b9e..00000000 --- a/source/installation/install-wheel.md +++ /dev/null @@ -1,26 +0,0 @@ -# Install the country package - -This section will allow you to run the [OpenFisca-Country-Template packaged library](https://pypi.org/project/OpenFisca-Country-Template/). - -It's the minimal installation when you need to run the model on your local environement and don't want to edit it. If you want to modify the model, just switch to the [install the OpenFisca-Country-Template in editable mode](./install-openfisca-country-template.md) section. - -## Install OpenFisca-Country-Template packaged library - -OpenFisca runs with [Python](https://www.python.org/). The following steps call [pip package installer](https://pypi.org/project/pip/) that requires a `Python` installation. To check its installation or install it, the [presets page](presets.md) is here for you! - -> When you have other Python projects on your local environement, we recommend you to create a new virtual environment to work in an isolated area and avoid dependencies conflicts. [Here is more information](https://github.com/openfisca/country-template#setting-up-a-virtual-environment-with-venv) from OpenFisca-Country-Template documentation. - -To install OpenFisca-Country-Template latest [published revision](https://pypi.org/project/OpenFisca-Country-Template/#history), run the following command in your terminal: - -```shell -pip install OpenFisca-Country-Template -``` - -It should end without error. You can see the installed packages by running: - -```shell -pip list -``` -`OpenFisca-Country-Template` should now be in the list. - -You're all set! `OpenFisca-Country-Template` is now installed and ready to run your calculations. diff --git a/source/installation/install-with-docker.md b/source/installation/install-with-docker.md index ed4f76f9..2c3b7f53 100644 --- a/source/installation/install-with-docker.md +++ b/source/installation/install-with-docker.md @@ -1,42 +1,48 @@ -# Install the country package with Docker +# Install with Docker -When you want to use OpenFisca, either to run it or edit its code, you need to setup a specific environement. +Using Containers such as Docker to install OpenFisca is useful when a reproducible environment is important or the [Installation requirements](installation-requirements.md) process is either not desirable or not possible. -If you don't want the OpenFisca environment to interfere with your pre-existing setup, or if you don't have one, you can use a container platform such as [Docker](https://www.docker.com) that will set everything up for you. It will allow you to run a minimal image of Unix operating system. -In a container, you will have an isolated environment with user rights to install OpenFisca. +A container platform such as [Docker](https://www.docker.com) sets up the required environment usually on a minimal image of a Unix operating system. +In a container, exists an isolated environment with user rights to install OpenFisca. The following instructions are for Docker, you may also want to check out [Podman.](https://podman.io). -> Install free [Docker Community Edition](https://docs.docker.com/install/#supported-platforms) (also named `Docker Desktop`). -> * Follow default installation instructions (you will need to create a free Docker ID). -> * Run installed Docker application (to activate docker daemon). -> On Windows operating system, you need to have Windows 10 or higher to use Docker. +> Install the free [Docker Community Edition](https://docs.docker.com/install/#supported-platforms) (also named `Docker Desktop`). +> +> - Follow default installation instructions (requires creation of a free Docker ID). +> - Run installed Docker application (to activate docker daemon). +> +> On the Windows operating system, Windows 10 or higher is required to use Docker. ## Install OpenFisca in a Docker container -Let's say that you want to install the [openfisca-country-template](https://github.com/openfisca/country-template) model (or your specific country model). And you want to work in a directory named `my-openfisca` where any change you do is visible on both sides, locally and on Docker. +These instructions are for the [openfisca-country-template](https://github.com/openfisca/country-template) but should be able to be followed for any OpenFisca country package. +The instructions create a directory named `my-openfisca` where any changes made are visible both on the local machine and in the Docker environment. + +1. Setup a working directory: + + For these instructions create a new directory named `my-openfisca`. + + Open the system console (`cmd.exe` for Windows OS, a bash Terminal for Unix/Linux/Mac) and run: -1. Go to your working directory: - * If you don't have one, create a new directory named `my-openfisca`. - - * Open your system console (`cmd.exe` for Windows OS, a bash Terminal for Unix/Linux/Mac) and run: ```sh cd my-openfisca # Updated with the real path to your working directory - ``` + ``` -2. Build a container with Python 3.7, Git and console commands. - > Git comes with Python image. +2. Build a container with the [appropriate Python version](installation-requirements.md#how-to-find-the-python-version-of-a-model), Git and console commands. + > Note that Git comes with the Python image. + + + For Linux/Unix/Mac operating systems, run the following command (swapping `python:3.11` for the appropriate Python version): - * For Linux/Unix/Mac operating systems, run: ```sh - docker run --rm -it -v $PWD:/my-openfisca -w /my-openfisca python:3.7 bash + docker run --rm -it -v $PWD:/my-openfisca -w /my-openfisca python:3.11 bash ``` - * For Windows operating system, run: + + For Windows operating system, run the following command (swapping `python:3.11` for the appropriate Python version): + ```sh - docker run --rm -it -v %cd%:/my-openfisca -w /my-openfisca python:3.7 bash - ``` + docker run --rm -it -v %cd%:/my-openfisca -w /my-openfisca python:3.11 bash + ``` + +3. Check the installed libraries with the `pip list` command. + This should result in the following list of packages: -3. Check for installed libraries with `pip list` command. - You should get this list of packages: ```sh Package Version ---------- ------- @@ -45,26 +51,31 @@ Let's say that you want to install the [openfisca-country-template](https://gith wheel *.*.* ``` -4. Install [openfisca-country-template](https://github.com/openfisca/country-template). Here are two main options: you can run it without modifying it or install it to edit its code. - - * To edit `openfisca-country-template`, get its source code with: +4. Install the [openfisca-country-template](https://github.com/openfisca/country-template). The chosen approach depends on the use case, specifically if the intention is to contribute to the rules. + + + To contribute to the `openfisca-country-template`, get its source code with: + ```sh git clone https://github.com/openfisca/country-template.git ``` - And, install it with: + + _Note for other OpenFisca country packages change the git repository address as appropriate._ + + Then, install it with: + ```sh cd country-template make install - ``` + ``` + + + Alternatively to run the `openfisca-country-template` without modifying it, install it as a library with: - * Or, to run `openfisca-country-template` without modifying it, install it as a library with: ```sh pip install openfisca_country_template ``` - In both cases, the installation should end without error, and the `pip list` response should contain `OpenFisca-Country-Template`. - + _Note for other OpenFisca country packages, check first if it is published on [https://pypi.org/](https://pypi.org/) and substitute `openfisca_country_template` for the appropriate package name._ -You're all set! You can now use `openfisca-country-template`. + In both cases, the installation should end without error, and the `pip list` response should contain `OpenFisca-Country-Template`. -Any changes to your `my-openfisca/` local files will be reflected to `my-openfisca/` files in Docker, and vice-versa. +This should complete the installation of `openfisca-country-template`, any changes to the local `my-openfisca/` files will be reflected in the `my-openfisca/` files in Docker, and vice-versa. diff --git a/source/installation/installation-requirements.md b/source/installation/installation-requirements.md new file mode 100644 index 00000000..0d5a0e79 --- /dev/null +++ b/source/installation/installation-requirements.md @@ -0,0 +1,66 @@ +# Installation requirements + +> Some use cases require an OpenFisca installation in a local environment where some tools should be pre-installed. First establish if the use case requires installation via the [getting started](./index.md) page. + +OpenFisca runs with [Python](https://www.python.org/). + +If the local environment already has an appropriate `Python` version (with `pip`) then this step can be skipped. Check the OpenFisca [country package for supported Python versions](installation-requirements.md#how-to-find-the-python-version-of-a-model). + +_All country templates depend on the [OpenFisca Core](https://github.com/openfisca/openfisca-core) package, at the time of writing, OpenFisca Core supports python versions 3.9 -> 3.11._ + +## Check Python installation + +To check the `pip` installation run this command in the local terminal: + +```shell +pip --version +``` + +If this results in `pip: command not found`, then installing Python is required. + +## Install Python + +`Python` installation is required to run OpenFisca code on a local environment. The `Python` version required depends on the OpenFisca country package to be installed. + +### How to find the Python version of a model + +These instructions apply to the `OpenFisca-Country-Template` by way of example, other country packages have a similar structure. + +To identify the Python revision of the `OpenFisca-Country-Template`: + +1. Check the [pyproject.toml](https://github.com/openfisca/country-template/blob/main/pyproject.toml)* of the [OpenFisca-Country-Template repository](https://github.com/openfisca/country-template), +2. Check the `classifiers` values where the Python version is described by a value like `"Programming Language :: Python :: 3.11"` (here `3.11`) +3. When multiple Python versions are listed, it is advised to install the most recent version (3.11 for example if 3.9, 3.10 and 3.11 are listed). + +_* In some older versions of country packages the information will instead be in the `setup.py` file at the root of the project_. + +### Install a Python version + +Python installation depends on the operating system. + +Follow the default installation instructions in the [Python official documentation](https://www.python.org/downloads/). Find the appropriate version required before proceeding to install. + +> [Docker](https://www.docker.com) users might find it easier to follow a different installation for Python and rely on [Python official image](https://hub.docker.com/_/python) instead. See the [Install with Docker](./install-with-docker.md) page. + +#### Recommendations for Windows users + +Microsoft Windows users can also utilise the [conda](https://docs.conda.io/en/latest/) package and environment manager to install the [OpenFisca-Country-Template](https://anaconda.org/search?q=openfisca-country-template) or one of the OpenFisca packages [published as conda packages](https://anaconda.org/search?q=openfisca). + +This option is recommended for easier installation but the [available packages list](https://anaconda.org/search?q=openfisca) is shorter. + +To install Python through conda: + +* install the [Anaconda distribution](https://anaconda.org) for Python and conda. +* or, also consider the minimal [Miniconda distribution](https://docs.conda.io/en/latest/miniconda.html) for Python and conda. + +## Contributing to the rules (Git) + +Source code is managed with the [Git](https://git-scm.com) version control system. If the use-case includes contributing to the rules, `Git` is going to be an essential requirement. + +To can check for a valid Git installation run this command: + +```shell +git --version +``` + +It should return the version of Git if Git is installed. If [Git](https://git-scm.com) isn't installed, follow the official [documentation to install Git](https://git-scm.com/downloads) for the latest version. diff --git a/source/installation/offline-environment.md b/source/installation/offline-environment.md index ac82dbbf..790e0d7c 100644 --- a/source/installation/offline-environment.md +++ b/source/installation/offline-environment.md @@ -1,61 +1,76 @@ -# Install in an offline environment +# Edge Case: Offline environment -If you need to install OpenFisca on a server with no Internet access, here is how to do it. +If there is a need to install OpenFisca on a server with no internet access, the following is how that can be achieved. -The big picture: download Python packages on a machine with Internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/). +The big picture: download Python packages on a machine with internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/). -We assume that it is possible to copy files to the server, for example via a USB stick. Or perhaps the server filters only outgoing connections, but accepts incoming connections allowing to copy the files. +It's assumed that it is possible to copy files to the server, i.e. via a USB stick. ## On the machine with Internet access -We are going to create a first virtualenv in which we'll use `pip` to download the `.whl` files in a specific directory. - -Here we use [pew](https://github.com/berdario/pew) to simplify virtualenv management. We also use `Python` v3.7 and `OpenFisca-France` model as an example that you can adapt to your country package; then, make sure to choose [your country package Python version](./presets.md#how-to-find-the-python-version-of-a-model)). +First create a virtual environment and use `pip` to download the `.whl` files to a specific directory. ```sh -pip install pew -pew new openfisca-packages --python=python3.7 - -# Upgrade pip itself -pip install --upgrade pip -pip --version -# Should print at least 9.0 at the time we write this doc. - -mkdir ~/openfisca-packages -cd ~/openfisca-packages -pip download OpenFisca-France -# You should see the downloaded files in the current directory. + mkdir ~/openfisca-packages + cd ~/openfisca-packages + + # Create and instigate a virtual environment + python3.11 -m venv .venv + source .venv/bin/activate + + # Upgrade pip itself + pip install --upgrade pip + pip --version + # Prints 24.0 at the time this doc was written. + + mkdir country-template + cd country-template + pip download OpenFisca-Country-Template + # You should see the downloaded files in the current directory. ``` -Now copy these files on the server (say in the `~/openfisca-packages` directory), either via a USB stick, or with `scp`, or any other way. +Copy the files in the `~/openfisca-packages/country-template` directory to the server via a USB stick, or for example with `scp`. Example with `scp`: ```sh -scp -r ~/openfisca-packages user@server: + scp -r ~/openfisca-packages/country-template user@server: ``` ## On the server -Starting from here we assume you copied the packages on the server, say in `~/openfisca-packages`. +The following assumes the files are now stored in `~/openfisca-packages/country-template` on the server. The following commands show how to install Python packages without any Internet access. -If you already have a virtualenv, activate it. Otherwise create a new one following the same instructions as above (for example with `pew new`). +If you already have a virtual environment, activate it. Otherwise create a new one following the same instructions as above. ```sh -pip install ~/openfisca-packages/* + pip install ~/openfisca-packages/country-template/* Processing ./isodate-0.5.4.tar.gz [...] - Installing collected packages: pytz, Babel, Biryani, numpy, PyYAML, OpenFisca-Core, requests, OpenFisca-France, isodate - Successfully installed Babel-2.3.4 Biryani-0.10.4 OpenFisca-Core-7.0.0 OpenFisca-France-15.1.0 PyYAML-3.12 isodate-0.5.4 numpy-1.12.0 pytz-2016.10 requests-2.13.0 + Installing collected packages: StrEnum, sortedcontainers, typing-extensions... openfisca-country-template + Successfully installed StrEnum, sortedcontainers, typing-extensions... openfisca-country-template + + # Step completed, the following can be utilised to confirm success and versions of the packages installed. + pip list | grep openfisca-country_template + openfisca-country_template 7.1.1 -pip list | grep OpenFisca-France - OpenFisca-France 15.1.0 + pip list | grep OpenFisca-Core + OpenFisca-Core 41.4.5 ``` -Run the basic tests which confirm that `OpenFisca-France` country package is correctly installed: +Now copy these files on the server (say in the `~/openfisca-packages` directory), either via a USB stick, or with `scp`, or any other way. + +Example with `scp`: ```sh -python -m openfisca_france.tests.test_basics -OpenFisca-France basic test was executed successfully. +scp -r ~/openfisca-packages user@server: +``` + +To check that everything works correctly, run the following command: + +```sh +python -c "from openfisca_country_template import CountryTaxBenefitSystem; CountryTaxBenefitSystem()" ``` + +No error message should appear. You can now utilise this environment to [run simulations](../simulate/run-simulation.md). diff --git a/source/installation/presets.md b/source/installation/presets.md deleted file mode 100644 index f5db8bda..00000000 --- a/source/installation/presets.md +++ /dev/null @@ -1,63 +0,0 @@ -# Presets to OpenFisca installation - -> Some use cases require an OpenFisca installation in a local environment where some tools should be pre-installed. First of all, check your use case in the [getting started](./index.md) page. - -OpenFisca runs with [Python](https://www.python.org/). -Its source code is managed through [Git](https://git-scm.com) version control system. - -If your local environement already has `Python` (with `pip`) and `Git`, you can skip this page and go to [getting started](./index.md) options. - -## Check Environment presets - -You can check the `pip` installation by running this command in your terminal: - -```shell -pip --version -``` - -If this results to `pip: command not found`, then you need to install Python. The [Install Python](./presets.md#install-python) section is here to help you through this journey. 🙂 - -Likewise, you can check your Git installation by running this command: - -```shell -git --version -``` - -It should return the version of your installed version control system. If [Git](https://git-scm.com) isn't installed on your local environment, you will find more information in the [Install Git](./presets.md#install-git) section below. - -## Install Python - -`Python` installation is compulsory to run OpenFisca code on your local environment. The `Python` version depend on the OpenFisca country model that you would like to use. - -### How to find the Python version of a model - -We describe here how to find the Python version of the `OpenFisca-Country-Template`. Other country models have a similar structure. - -To identify the Python revision of the `OpenFisca-Country-Template`: -1. Look into the [setup.py file](https://github.com/openfisca/country-template/blob/master/setup.py) of [OpenFisca-Country-Template repository](https://github.com/openfisca/country-template), -2. Check the `classifiers` values where the Python version is described by a value like `"Programming Language :: Python :: 3.7"` (here `3.7`) -3. When multiple Python versions are listed, we advise you to install the most recent one (3.8 for example if 3.7 and 3.8 are listed). - -### Install a Python version - -Python installation depends on your operating system. - -You will find the default installation instructions in [Python official documentation](https://www.python.org/downloads/). See the Python version of your model as described above before choosing wich Python to install. - -> [Docker](https://www.docker.com) users might find it easier to follow a different installation for Python and rely on [Python official image](https://hub.docker.com/_/python) instead. See the [Install OpenFisca in a Docker container](./install-with-docker.md) page. - -#### Recommendations for Windows users - -Microsoft Windows users, can also rely [conda](https://docs.conda.io/en/latest/) package and environment manager to use [OpenFisca-Country-Template](https://anaconda.org/search?q=openfisca-country-template) or one of the openfisca packages [published as conda packages](https://anaconda.org/search?q=openfisca). - -We recommend this option for an easier installation but the [available packages list](https://anaconda.org/search?q=openfisca) is shorter. - -To install Python through conda: -* install the [Anaconda distribution](https://anaconda.org) for Python and conda. -* or, for users with less disk space, install the minimal [Miniconda distribution](https://docs.conda.io/en/latest/miniconda.html) for Python and conda. - -## Install Git - -`Git` installation is compulsory to push your contributions to OpenFisca code to the shared repository. - -Here is the [documentation to install Git](https://git-scm.com/downloads) latest revision. diff --git a/source/installation/python-api-browser.md b/source/installation/python-api-browser.md new file mode 100644 index 00000000..b3db21aa --- /dev/null +++ b/source/installation/python-api-browser.md @@ -0,0 +1,24 @@ +# Python API in the browser + +Some online services offer the opportunity to run Python code online without having to install anything on a local machine. + +To run OpenFisca directly in the browser for a simulation or to evaluate the impact of a reform, the following services could be useful: [Gitpod](https://www.gitpod.io/), [repl.it](https://repl.it), [python anywhere](https://www.pythonanywhere.com) and [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/). + +There is a lot of variance between the above services so rather than offer specific instructions, the following is the type of approach that will be required. + +## Instructions + +1. Start by [installing the package](install-country-package.md) on the online service e.g. `OpenFisca-Country-Template`. + +2. Write the code the use case requires. The following is an example of a python code snippet to run against the Python API: + + ```py + from openfisca_country_template import CountryTaxBenefitSystem + + tax_benefit_system = CountryTaxBenefitSystem() + parameters = tax_benefit_system.parameters + + print(parameters) + ``` + +3. Run the code; check the results. diff --git a/source/installation/windows-no-admin.md b/source/installation/windows-no-admin.md index ee486c34..0f1a6008 100644 --- a/source/installation/windows-no-admin.md +++ b/source/installation/windows-no-admin.md @@ -1,10 +1,10 @@ -# Install on Windows without admin rights +# Edge Case: Windows (not administrator) -_⚠️ Warning: running OpenFisca on a machine **with** administrator privileges would make your life much easier. Using a MacOS or a Linux would be even better._ +_⚠️ Warning: running OpenFisca on a machine **with** administrator privileges would be much easier. Using MacOS or Linux would be even better._ -_If you do not have a choice other than using a restricted Windows, this guide sums up the "recipe" to install OpenFisca in such an environment._ +_If you do not have a choice other than using a restricted Windows, this guide sums up one "recipe" to install OpenFisca in such an environment._ -The following steps are shared as an example of the process and only applied to an old OpenFisca-France revision ([v.18.9.10](https://github.com/openfisca/openfisca-france/blob/master/CHANGELOG.md#18910-829)). +The following steps are shared as an example of the process and were written for an old OpenFisca-France revision ([v.18.9.10](https://github.com/openfisca/openfisca-france/blob/master/CHANGELOG.md#18910-829)). ## 1. Install Git @@ -15,11 +15,11 @@ Git is a tool that will help you version your work. It also comes with a shell * ## 2. Install Python -Python is the programing language used in OpenFisca. It can be installed without administrators rights through a software named Miniconda. +Python is the programming language used in OpenFisca. It can be installed without administrator rights through a software named Miniconda. -- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose [your country package Python version](./presets.md#how-to-find-the-python-version-of-a-model) for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit. -- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, but in all case **copy paste the path to this folder somewhere**. It will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`. -- Run the program "Git Bash" from the "Start" menu ("Démarrer"). This should open a command line. Copy and paste the following lines in the console, after **adapting the first line using the path you noted in the last step and the python version** (set to `3.7` here): +- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose [the country package Python version](./installation-requirements.md#how-to-find-the-python-version-of-a-model) for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit. +- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, but in all cases **copy and paste the path to this folder somewhere**. It will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`. +- Run the program "Git Bash" from the "Start" menu. This should open a command line. Copy and paste the following lines in the console, be sure to **adapt the first line using the path you noted in the last step** and **set the python version to the correct one** (set to `3.11` here): ```sh echo 'MINICONDA_PATH="C:\Users\form\AppData\Local\Miniconda2"' >> .bashrc @@ -39,26 +39,28 @@ To check that everything worked correctly, type in Git Bash: pip --version ``` -A version number should be printed, and no error message should appear. Congrats, you just set up a Python working environment! +A version number should be printed, and no error message should appear. This indicates a functional Python working environment! ## 3. Install OpenFisca -- Download the country package installation files: openfisca package + dependencies. Here is an example with [OpenFisca-France v.18.9.10 files](https://github.com/openfisca/openfisca-france-offline/archive/master.zip) +For this example, we will utilise the `OpenFisca-France` package. For a different model you could achieve the same result by following the [offline environment](offline-environment) example to get local copies of the required packages. + +- Download the country package installation files: OpenFisca package + dependencies. Here is an example with [OpenFisca-France v.18.9.10 files](https://github.com/openfisca/openfisca-france-offline/archive/master.zip) - Extract the content of this archive in a directory. - Go to that directory, then to the `windows` subdirectory. If you installed Python in 32 bits, **right-click** on `32-bits`. If you installed Python in 64 bits, **right-click** on the `64-bits` subdirectory. Choose "Git Bash Here" - Run the command `pip install *` -To check that everything worked correctly, type in Git Bash: +To check that everything works correctly, run the following command in Git Bash: ```sh python -c "from openfisca_france import CountryTaxBenefitSystem; CountryTaxBenefitSystem()" ``` -No error message should appear. Congrats, you just installed OpenFisca-France! +No error message should appear. If that is the case the country package is successfully installed. ## 4. Install atom -Atom is a modern text editor that doesn't require administrator priviledges to be installed. It will allow you to edit Python files with syntaxing coloring. +Atom is a modern text editor that doesn't require administrator privileges to be installed. It will allow you to edit Python files with syntaxing colouring. - Download atom from [https://atom.io/](https://atom.io/) @@ -74,4 +76,4 @@ To run it, save your modifications, go to the directory containing it, right cli python name-of-the-script.py ``` -In case you run into a problem, please [open an issue](https://github.com/openfisca/openfisca-core/issues/new). +In case you run into a problem, please open an issue on the appropriate OpenFisca country repository, or if you can determine the issue is in OpenFisca Core, [open an issue here](https://github.com/openfisca/openfisca-core/issues/new).