CuCoPy - Currency Conversion for Python

The CuCoPy package provides methods for exchanging currencies and adjusting monetary values for inflation until 1960 on a yearly basis.

Features

• Adjust money for inflation (1960 - last calendar year)
• Exchange currencies from 60+ countries.
• Data sources: Exchange rates (ER) and Consumer Price Index (CPI) from the International Monetary Fund (IMF) API and IMF Data Explorer

Note on the Euro: For countries using the Euro (EUR), CuCoPy assumes the harmonized inflation value for the Euro Area.

Missing countries: If the ER or CPI of a country's currency is missing for your conversion, please contact the developers to request support.

Installation

Installation from conda-forge

CuCoPy can be installed into a new environment with the following command

mamba create -n -c conda-forge cucopy_env cucopy

Or can be installed into an existing environment with

mamba install -c conda-forge cucopy

Note on Mamba vs.Conda: mamba commands can be substitued with conda. We highly recommend using (Micro-)Mamba instead of Conda. The recommended way to use Mamba on your system is to install the Miniforge distribution. They offer installers for Windows, Linux and OS X. In principle, Conda and Mamba are interchangeable. The commands and concepts are the same. The distributions differ in the methodology for determining dependencies when installing Python packages. Switching to Mamba usually does not lead to any problems, as it is virtually identical to Conda in terms of operation.

Installation from pypi into a conda envrionment

First create a new environment that contains python and pip

mamba create -n cucopy_env python pip

Activate the environment

mamba activate cucopy_env

CuCoPy can be installed directly via pip:

pip install cucopy

Note on using pip within a conda environment To install packages within a conda environment, pip must already be installed in that environment. Please see this Stack Overflow post and this Anaconda Article.

Local installation for Development

Alternatively, it can also be installed via git - this will preserve the connection to the GitHub repository:

git clone https://github.com/FZJ-IEK3-VSA/CuCoPy

Change the directory into the new repository

cd cucopy

Installation with Conda Dependencies

Create a new environment with all necessary conda depenendcies

mamba env create -f env.yml

Install the local package in development mode

pip install -e . --no-deps

Installation with PyPi Dependencies

Then install CuCoPy via python as follows

pip install -e .

Example

In the following code section, the value in 2020 Euro is converted to the value in 2025 USD.

from cucopy import Currency
cur = Currency()

cur.convert_currency(value=100, base_year="2020", base_currency="EUR", target_year="2025", target_currency="USD", operation_order="inflation_first")
>> 137.41

For a deeper look into the features of CuCoPy, is a tutorial notebook available.

License

MIT License

Copyright (C) 2021-2026 FZJ-ICE-2

Active Developers: Maxime Gorres, Jan Göpfert, Patrick Kuckertz, Jann Weinand

Alumni: Julian Schönau, Leander Kotzur, Detlef Stolten

You should have received a copy of the MIT License along with this program. If not, see https://opensource.org/licenses/MIT

About Us

We are the Institute of Climate and Energy Systems (ICE) - Jülich Systems Analysis belonging to the Forschungszentrum Jülich. Our interdisciplinary department's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks.

Acknowledgements

The CuCoPy package relies heavily on the datasets made available by the International Monetary Fund (IMF), but is neither affiliated with or endorsed by either parties.

The IMF API provides information on international exchange rates as well as consumer price indices and is used for research purposes. Their terms can be accessed here: https://www.imf.org/external/terms.htm

This work was supported by the Federal Ministry for Economic Affairs and Climate Action (BMWK) with a grant for the project LOD-GEOSS (03EI1005B).