{"id":23831950,"url":"https://github.com/csdms/babelizer","last_synced_at":"2025-09-07T11:31:20.198Z","repository":{"id":39627434,"uuid":"128246828","full_name":"csdms/babelizer","owner":"csdms","description":"Transform BMI-wrapped models into Python packages","archived":false,"fork":false,"pushed_at":"2024-12-23T22:46:23.000Z","size":911,"stargazers_count":4,"open_issues_count":18,"forks_count":3,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2024-12-23T23:27:50.267Z","etag":null,"topics":["bmi","c","csdms","cxx","fortran","hacktoberfest","pymt","python"],"latest_commit_sha":null,"homepage":"https://babelizer.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csdms.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.rst","code_of_conduct":"CODE-OF-CONDUCT.rst","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-05T18:21:31.000Z","updated_at":"2024-04-11T18:05:28.000Z","dependencies_parsed_at":"2024-04-10T17:56:48.844Z","dependency_job_id":"e57551d7-6827-4577-bc4c-64382bb3cc54","html_url":"https://github.com/csdms/babelizer","commit_stats":{"total_commits":112,"total_committers":3,"mean_commits":"37.333333333333336","dds":0.5803571428571428,"last_synced_commit":"56ce18b89966144f5788dfaa7b0819ddee966899"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csdms%2Fbabelizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csdms%2Fbabelizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csdms%2Fbabelizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csdms%2Fbabelizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csdms","download_url":"https://codeload.github.com/csdms/babelizer/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232206387,"owners_count":18488512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bmi","c","csdms","cxx","fortran","hacktoberfest","pymt","python"],"created_at":"2025-01-02T14:16:42.668Z","updated_at":"2025-01-02T14:16:43.394Z","avatar_url":"https://github.com/csdms.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://joss.theoj.org/papers/10.21105/joss.03344/status.svg\n    :target: https://doi.org/10.21105/joss.03344\n\n.. image:: https://github.com/csdms/babelizer/workflows/Build/Test%20CI/badge.svg\n    :target: https://github.com/csdms/babelizer/actions?query=workflow%3A%22Build%2FTest+CI%22\n\n.. image:: https://anaconda.org/conda-forge/babelizer/badges/version.svg\n    :target: https://anaconda.org/conda-forge/babelizer\n\n.. image:: https://readthedocs.org/projects/babelizer/badge/?version=latest\n        :target: https://babelizer.readthedocs.io/en/latest/?badge=latest\n        :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n        :target: https://github.com/csdms/babelizer\n\n.. image:: https://coveralls.io/repos/github/csdms/babelizer/badge.svg?branch=develop\n    :target: https://coveralls.io/github/csdms/babelizer?branch=develop\n\n\nThe Babelizer: Wrap BMI libraries with Python bindings\n======================================================\n\n\nThe *babelizer* is a utility for wrapping a library that exposes a `Basic Model Interface`_ (BMI) so that it can be\nimported as a Python package.\n\nSupported languages include:\n\n*  C\n*  C++\n*  Fortran\n*  Python\n\n\nThe Babelizer is part of the CSDMS Workbench\n--------------------------------------------\n\nThe *babelizer* is an element of the `CSDMS Workbench`_,\nan integrated system of software tools, technologies, and standards\nfor building and coupling models. The Workbench provides two Python\nframeworks for model coupling, *pymt* and *landlab*.\nThe *babelizer* was written to bring models written in other languages into\nthese frameworks.\nHowever, as long as your model\nsatisfies the requirements below, you can use the *babelizer*\nto bring your model into Python without having to use any of the\nother tools in the Workbench.\n\n\nShould I use the babelizer?\n---------------------------\n\nTo determine if the\n*babelizer* is right for you, first be aware of a few requirements.\n\n1. Your model must be written in C, C++, Fortran, or Python\n2. Your model must provide a shared library\n3. Your model must expose a `Basic Model Interface`_ through this library\n\nThe most difficult of the three requirements is the last--implementing a BMI. This\ninvolves adding a series of functions with prescribed names,\narguments, and return values for querying and controlling your model. We have created\nseveral resources to help you understand the BMI and to guide you\nthrough the implementation process.\n\nBMI resources\n^^^^^^^^^^^^^\n\n* The `Basic Model Interface`_ documentation provides an overview of the BMI as well\n  as a detailed description of all of the BMI functions.\n* The following provide a BMI specification for each of the supported languages:\n\n  * `C spec \u003chttps://github.com/csdms/bmi-c/\u003e`_\n  * `C++ spec \u003chttps://github.com/csdms/bmi-cxx/\u003e`_\n  * `Fortran spec \u003chttps://github.com/csdms/bmi-fortran/\u003e`_\n  * `Python spec \u003chttps://github.com/csdms/bmi-python/\u003e`_\n\n* The following give examples of a BMI implementation for each of the supported languages:\n\n  * `C example \u003chttps://github.com/csdms/bmi-example-c/\u003e`_\n  * `C++ example \u003chttps://github.com/csdms/bmi-example-cxx/\u003e`_\n  * `Fortran example \u003chttps://github.com/csdms/bmi-example-fortran/\u003e`_\n  * `Python example \u003chttps://github.com/csdms/bmi-example-python/\u003e`_\n\nNote\n^^^^\n\nThere are lots of other good reasons to create a BMI for\nyour model--not just so you can bring it into Python with the *babelizer*!\nRead all about them in the `Basic Model Interface`_ documentation.\n\n\nRequirements\n------------\n\nThe *babelizer* requires Python \u003e=3.10.\n\n\nApart from Python, the *babelizer* has a number of other requirements, all of which\ncan be obtained through either *pip* or *conda*, that will be automatically\ninstalled when you install the *babelizer*.\n\nTo see a full listing of the requirements, have a look at the project's\n*requirements.txt* file.\n\nIf you are a developer of the *babelizer* you will also want to install\nadditional dependencies for running the *babelizer*'s tests to make sure\nthat things are working as they should. These dependencies are listed\nin *requirements-testing.txt*.\n\n\nInstallation\n------------\n\nTo install the *babelizer*, first create a new environment.\nAlthough this isn't strictly necessary, it\nisolates the installation to avoid conflicts with your\nbase Python installation. This can be done with *conda*:\n\n.. code:: bash\n\n    $ conda create -n babelizer python=3\n    $ conda activate babelizer\n\nStable Release\n^^^^^^^^^^^^^^\n\nThe *babelizer* and its dependencies are best installed with *conda*:\n\n.. code:: bash\n\n    $ conda install babelizer -c conda-forge\n\nFrom Source\n^^^^^^^^^^^\n\nAfter downloading the the *babelizer* source code, run the following from\n*babelizer*'s top-level directory (the one that contains *setup.py*) to\ninstall *babelizer* into the current environment:\n\n.. code:: bash\n\n    $ pip install -e .\n\nor using *conda*:\n\n.. code:: bash\n\n    $ conda install --file=requirements.txt -c conda-forge\n\n\nInput file\n----------\n\nThe *babelizer* requires a single *toml*-formatted input file that describes\nthe library to wrap. This file is typically named *babel.toml*.\nAn example of a blank *babel.toml* file:\n\n.. code:: toml\n\n    [library]\n    [library.\"\u003cname\u003e\"]\n    language = \"c\"\n    library = \"\"\n    header = \"\"\n    entry_point = \"\"\n\n    [build]\n    undef_macros = []\n    define_macros = []\n    libraries = []\n    library_dirs = []\n    include_dirs = []\n    extra_compile_args = []\n\n    [package]\n    name = \"\"\n    requirements = []\n\n    [info]\n    github_username = \"pymt-lab\"\n    package_author = \"csdms\"\n    package_author_email = \"csdms@colorado.edu\"\n    package_license = \"MIT\"\n    summary = \"\"\n\n    [ci]\n    python_version = [\"3.9\"]\n    os = [\"linux\", \"mac\", \"windows\"]\n\nYou can generate *babel.toml* files using the *babelize generate* command.\nFor example, the above *babel.toml* was generated with:\n\n.. code:: bash\n\n  $ babelize generate \u003e babel.toml\n\nLibrary section\n^^^^^^^^^^^^^^^\n\nThe *library* section specifies information about the library being babelized.\n\nName\n\"\"\"\"\n\nThe name of the babelized class.\nThis will be a Python class,\nso it should follow Python naming conventions such as camel-case typing.\n\nLanguage\n\"\"\"\"\"\"\"\"\n\nThe programming language of the library (possible values are \"c\", \"c++\",\n\"fortran\", and \"python\").\n\n.. code:: toml\n\n  [library]\n  language = \"c\"\n\nLibrary\n\"\"\"\"\"\"\"\n\nThe name of the BMI library to wrap.\nThis is the text passed to the linker through the `-l` option;\nfor example, use \"foo\" for a library *libfoo.a*.\n\nHeader\n\"\"\"\"\"\"\n\nThe name of the header file (*.h*, *.hxx*) declaring the BMI class.\nThis option is only needed when wrapping C and C++ libraries.\n\nEntry point\n\"\"\"\"\"\"\"\"\"\"\"\n\nThe name of the BMI entry point into the library.\nFor object-oriented languages,\nthis is typically the name of a class that implements the BMI.\nFor procedural languages,\nthis is typically a function.\n\nAn example of a C++ library (*bmi_child*), exposing a class *BmiChild* (which\nimplements a BMI) might look like the following:\n\n.. code:: toml\n\n   [library]\n   [library.Child]\n   language = \"c++\"\n   library = \"bmi_child\"\n   header = \"bmi_child.hxx\"\n   entry_point = \"BmiChild\"\n\nwhereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (which\nimplements a BMI) might look like:\n\n.. code:: toml\n\n   [library]\n   [library.Cem]\n   language = \"c\"\n   library = \"bmi_cem\"\n   header = \"bmi_cem.h\"\n   entry_point = \"register_bmi_cem\"\n\nBuild section\n^^^^^^^^^^^^^\n\nIn the build section the user can specify flags to pass to the compiler\nwhen building the extension.\n\nPackage section\n^^^^^^^^^^^^^^^\n\nName and extra requirements needed to build the babelized library.\n\nName\n\"\"\"\"\n\nName to use for the wrapped package. This is used when creating the new\npackage *\u003cpackage_name\u003e*. For example, the following will create\na new package, *pymt_foo*.\n\n.. code:: toml\n\n  [package]\n  name = \"pymt_foo\"\n\nRequirements\n\"\"\"\"\"\"\"\"\"\"\"\"\n\nList of packages required by the library being wrapped. For example, the\nfollowing indicates that the packages *foo* and *bar* are dependencies\nfor the package.\n\n.. code:: toml\n\n  [package]\n  requirements = [ \"foo\", \"bar\",]\n\nInfo section\n^^^^^^^^^^^^\n\nDescriptive information about the package.\n\nGithub username\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nThe GitHub username or organization where this package will be hosted. This\nis used in generating links to the CI, docs, etc.\n\nAuthor\n\"\"\"\"\"\"\n\nAuthor of the wrapped package. Note that this is not the author of the\nlibrary being wrapped, just the code generated by the *babelizer*.\n\nEmail\n\"\"\"\"\"\n\nContact email to use for the wrapped package.\n\nLicense\n\"\"\"\"\"\"\"\n\nSpecify the Open Source license for the wrapped package. Note that this is not the\nlicense for the library being wrapped, just for the code generated by the *babelizer*.\n\nSummary\n\"\"\"\"\"\"\"\n\nA short description of the wrapped library.\n\nCi section\n^^^^^^^^^^\n\nInformation about how to set up continuous integration.\n\n.. code:: toml\n\n    [ci]\n    python_version = [\"3.7\", \"3.8\", \"3.9\"]\n    os = [\"linux\", \"mac\", \"windows\"]\n\n\nPython version\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nA list of Python versions to build and test the generated project with.\n\nOperating system\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nA list of operating systems to build the generate project on. Supported values are\n*linux*, *mac*, and *windows*.\n\nExample babel.toml\n^^^^^^^^^^^^^^^^^^\n\nBelow is an example of a *babel.toml* file that describes a shared library,\nwritten in C. In this example, the library, *bmi_hydrotrend*, exposes the\nfunction *register_bmi_hydrotrend* that implements a BMI for a component\ncalled *hydrotrend*.\n\n.. code:: toml\n\n    [library]\n    [library.Hydrotrend]\n    language = \"c\"\n    library = \"bmi_hydrotrend\"\n    header = \"bmi_hydrotrend.h\"\n    entry_point = \"register_bmi_hydrotrend\"\n\n    [build]\n    undef_macros = []\n    define_macros = []\n    libraries = []\n    library_dirs = []\n    include_dirs = []\n    extra_compile_args = []\n\n    [package]\n    name = \"pymt_hydrotrend\"\n    requirements = [\"hydrotrend\"]\n\n    [info]\n    github_username = \"pymt-lab\"\n    package_author = \"csdms\"\n    package_author_email = \"csdms@colorado.edu\"\n    package_license = \"MIT\"\n    summary = \"PyMT plugin for hydrotrend\"\n\n    [ci]\n    python_version = [\"3.7\", \"3.8\", \"3.9\"]\n    os = [\"linux\", \"mac\", \"windows\"]\n\nYou can use the ``babelize sample-config`` command to generate\na sample *babel.toml* file to get you started. For example,\nthe above *babel.toml* can be generated with the following,\n\n.. code:: bash\n\n    babelize sample-config\n\nUse\n---\n\nGenerate Python bindings for a library that implements a BMI,\nsending output to the current directory\n\n.. code:: bash\n\n    babelize init babel.toml\n\nUpdate an existing repository\n\n.. code:: bash\n\n  babelize update\n\nFor a complete example of using the *babelizer*\nto wrap a C library exposing a BMI,\nsee the User Guide of the `documentation`_.\n\n\n.. Links:\n\n.. _Basic Model Interface: https://bmi.readthedocs.io/\n.. _CSDMS Workbench: https://csdms.colorado.edu/wiki/Workbench\n.. _documentation: https://babelizer.readthedocs.io/\n.. _BMI C: https://github.com/csdms/bmi-c/\n.. _BMI C++: https://github.com/csdms/bmi-cxx/\n.. _BMI Fortran: https://github.com/csdms/bmi-fortran/\n.. _BMI Python: https://github.com/csdms/bmi-python/\n.. _BMI example C: https://github.com/csdms/bmi-example-c/\n.. _BMI example C++: https://github.com/csdms/bmi-example-cxx/\n.. _BMI example Fortran: https://github.com/csdms/bmi-example-fortran/\n.. _BMI example Python: https://github.com/csdms/bmi-example-python/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsdms%2Fbabelizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsdms%2Fbabelizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsdms%2Fbabelizer/lists"}