# Python tooling for FlightGear development
This package contains Python modules and scripts used for development of the
[FlightGear](https://www.flightgear.org/) flight simulator. It is built from
an official FlightGear repository called FGMeta, uploaded by FlightGear
developers but does not contain the flight simulator itself. If you are
interested in the latter, please visit its
[home page](https://www.flightgear.org/).
This package is mostly of interest to FlightGear developers. The
internationalization scripts it ships can be useful for aircraft and
add-on developers that want to add translations to their work.
There is nothing special about the packaging. The following instructions
are for people familiar with FlightGear but not necessarily with `pip` and
Python `venv`s.
Note: `python3-flightgear` is the directory containing this package in the
[FGMeta](https://gitlab.com/flightgear/fgmeta) repository.
## Telling your Python interpreter how to access the modules
For users of FGMeta: in order to run most of the Python scripts in FGMeta,
your Python 3 installation must have the
`/path/to/fgmeta/python3-flightgear/src` directory in its `sys.path`. If
you use `pip`, the easiest way to ensure this is to install the
`flightgear` Python package (see below). This will also create the scripts
shipped with the package, contrary to a simple modification of
`PYTHONPATH` (which is one of the ways to alter `sys.path`).
### Recommended method for development
The following instructions should be carried out under a normal user
account (not root). They assume you already have a clone of the
[FGMeta](https://gitlab.com/flightgear/fgmeta) repository in
`/path/to/fgmeta`.
1. Create a Python [venv](https://docs.python.org/3/library/venv.html) in
some directory `dir` of your choice (outside FGMeta):
python3 -m venv dir
2. Install the `flightgear` package inside the venv. We use option `-e`
here to tell `pip` to install the project in editable mode, so that
when files in `/path/to/fgmeta/python3-flightgear` are updated, the
result is immediately usable from your venv without having to install
the package again:
dir/bin/pip install -e /path/to/fgmeta/python3-flightgear
Now you have the Python modules nicely installed under `dir` and the
associated scripts in `dir/bin`. If you're interested in `some-script`
from this package, you can invoke it as `dir/bin/some-script` or create
a symbolic link to it from a directory that is in your `PATH`. (You
might want to add `dir/bin` to your `PATH` for simplicity, however
please note before doing so that it has `python`, `python3` and `pip`
executables. Your call.)
Note: the `flightgear` Python package installed with the above command
can be uninstalled from the venv using:
dir/bin/pip uninstall flightgear
3. If the underlying Python installation is updated (as in, from Python
X.Y to Python X.Y+1) or if the venv directory is moved elsewhere (which
includes one of its parents being moved or renamed), you'll have to
recreate the venv: simply delete the `dir` directory and redo the
preceding steps.
### Alternate way
Another, more manual possibility, is to modify the `PYTHONPATH`
environment variable, either directly or by creating a `.pth` file. This
has a few drawbacks as compared to the “recommended way”:
- it won't warn you if your Python version is unsuitable for running the
code in `fgmeta/python3-flightgear`;
- it won't warn you if you don't have required dependencies (the
“recommended way” would automatically install them using `pip`);
- it won't create the scripts declared in the `pyproject.toml` file
(however, they can currently be invoked as Python modules).
So, how does it work? For instance, you can use something like the
following in your shell setup:
export PYTHONPATH="/path/to/fgmeta/python3-flightgear/src"
This example uses Bourne-style shell syntax; adjust for your particular
shell. Several directories may be added this way using a colon separator
on Unix or macOS (`:`), and a semicolon on Windows (`;`).
An alternative to setting `PYTHONPATH` is to add `.pth` files in special
directories of your Python installation(s). For instance, you could create
a file, say, `FlightGear-meta.pth`, containing a single line (with no
space at the beginning):
/path/to/fgmeta/python3-flightgear/src
If you want the modules present in
`/path/to/fgmeta/python3-flightgear/src` to be accessible to a particular
Python interpreter (say, a Python 3.8), simply put the `.pth` file in
`/path/to/python-install-dir/lib/python3.8/site-packages/`. This can even
be a virtual environment if you want—that is basically how `pip` installs
packages in editable mode inside a venv. For the system Python
interpreters on Debian, you can put the `.pth` file in, e.g,
`/usr/local/lib/python3.8/dist-packages/`. Note that you may add more
lines to a `.pth` file in case you want to add other paths to the Python
interpreter's `sys.path`.
## The scripts
Once you've done the above setup, the Python modules from
`fgmeta/python3-flightgear/src` should be available to the chosen Python
interpreter. What about scripts that rely on these modules?
Most scripts are declared in `python3-flightgear/pyproject.toml` and
automatically created by the `pip install` command from the “Recommended
method for development” (remember: use `dir/bin/pip install` if you want
the installation to happen under the `dir` venv). There may be a few
exceptions, like currently `catalog/update-catalog.py` which exists as a
standalone script in FGMeta. As long as the modules from
`fgmeta/python3-flightgear/src` are installed for Python (i.e., accessible
via its `sys.path`), which the above methods ensure, such scripts will
work too.
The only remaining problem is therefore the following: if you used the
“alternate way”, you don't have the scripts that `pip install` would have
created for you in the “recommended way”. However, these scripts are
currently available as Python modules. For instance, the file
`python3-flightgear/src/flightgear/meta/scripts/i18n/fg_extract_translatable_strings.py`
can be imported as a Python module. Example: the command
python3 -m flightgear.meta.scripts.i18n.fg_extract_translatable_strings --help
is equivalent to
fg-extract-translatable-strings --help
This might be useful for one-off uses of the scripts like in Continuous
Integration, where one doesn't necessarily want to run `pip`: one could
set `PYTHONPATH` and run the desired module(s) as above (the obvious
alternative being to create a temporary venv and use the “recommended
way”).
## Running the unit tests
Once the modules in `python3-flightgear/src` are visible to Python
(regardless of the method used), the unit tests of this package can be run
with:
cd python3-flightgear
python3 -m unittest
(the second command is equivalent to `python3 -m unittest discover`; more
details in `tests/README.md`).
## Building the package
In case you want to build the package, you can do:
cd python3-flightgear
python3 -m build
This requires the Python `build` tool as explained in the
[Python Packaging User Guide](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#packaging-your-project).
Raw data
{
"_id": null,
"home_page": null,
"name": "FlightGear",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Florent Rougon <f.rougon@frougon.net>, James Turner <james@flightgear.org>",
"keywords": "FlightGear, flightgear, flight, simulator, tools",
"author": null,
"author_email": "Florent Rougon <f.rougon@frougon.net>, James Turner <james@flightgear.org>",
"download_url": "https://files.pythonhosted.org/packages/68/8b/aa902bc4411e62dc3def90fe87ed084b2672baf2e85b084a2b9a42389fd6/flightgear-1.0.0a1.tar.gz",
"platform": null,
"description": "# Python tooling for FlightGear development\n\nThis package contains Python modules and scripts used for development of the\n[FlightGear](https://www.flightgear.org/) flight simulator. It is built from\nan official FlightGear repository called FGMeta, uploaded by FlightGear\ndevelopers but does not contain the flight simulator itself. If you are\ninterested in the latter, please visit its\n[home page](https://www.flightgear.org/).\n\nThis package is mostly of interest to FlightGear developers. The\ninternationalization scripts it ships can be useful for aircraft and\nadd-on developers that want to add translations to their work.\n\nThere is nothing special about the packaging. The following instructions\nare for people familiar with FlightGear but not necessarily with `pip` and\nPython `venv`s.\n\nNote: `python3-flightgear` is the directory containing this package in the\n[FGMeta](https://gitlab.com/flightgear/fgmeta) repository.\n\n## Telling your Python interpreter how to access the modules\n\nFor users of FGMeta: in order to run most of the Python scripts in FGMeta,\nyour Python\u00a03 installation must have the\n`/path/to/fgmeta/python3-flightgear/src` directory in its `sys.path`. If\nyou use `pip`, the easiest way to ensure this is to install the\n`flightgear` Python package (see below). This will also create the scripts\nshipped with the package, contrary to a simple modification of\n`PYTHONPATH` (which is one of the ways to alter `sys.path`).\n\n### Recommended method for development\n\nThe following instructions should be carried out under a normal user\naccount (not root). They assume you already have a clone of the\n[FGMeta](https://gitlab.com/flightgear/fgmeta) repository in\n`/path/to/fgmeta`.\n\n1. Create a Python [venv](https://docs.python.org/3/library/venv.html) in\n some directory `dir` of your choice (outside FGMeta):\n\n python3 -m venv dir\n\n2. Install the `flightgear` package inside the venv. We use option `-e`\n here to tell `pip` to install the project in editable mode, so that\n when files in `/path/to/fgmeta/python3-flightgear` are updated, the\n result is immediately usable from your venv without having to install\n the package again:\n\n dir/bin/pip install -e /path/to/fgmeta/python3-flightgear\n\n Now you have the Python modules nicely installed under `dir` and the\n associated scripts in `dir/bin`. If you're interested in `some-script`\n from this package, you can invoke it as `dir/bin/some-script` or create\n a symbolic link to it from a directory that is in your `PATH`. (You\n might want to add `dir/bin` to your `PATH` for simplicity, however\n please note before doing so that it has `python`, `python3` and `pip`\n executables. Your call.)\n\n Note: the `flightgear` Python package installed with the above command\n can be uninstalled from the venv using:\n\n dir/bin/pip uninstall flightgear\n\n3. If the underlying Python installation is updated (as in, from Python\n X.Y to Python X.Y+1) or if the venv directory is moved elsewhere (which\n includes one of its parents being moved or renamed), you'll have to\n recreate the venv: simply delete the `dir` directory and redo the\n preceding steps.\n\n### Alternate way\n\nAnother, more manual possibility, is to modify the `PYTHONPATH`\nenvironment variable, either directly or by creating a `.pth` file. This\nhas a few drawbacks as compared to the \u201crecommended way\u201d:\n\n- it won't warn you if your Python version is unsuitable for running the\n code in `fgmeta/python3-flightgear`;\n\n- it won't warn you if you don't have required dependencies (the\n \u201crecommended way\u201d would automatically install them using `pip`);\n\n- it won't create the scripts declared in the `pyproject.toml` file\n (however, they can currently be invoked as Python modules).\n\nSo, how does it work? For instance, you can use something like the\nfollowing in your shell setup:\n\n export PYTHONPATH=\"/path/to/fgmeta/python3-flightgear/src\"\n\nThis example uses Bourne-style shell syntax; adjust for your particular\nshell. Several directories may be added this way using a colon separator\non Unix or macOS (`:`), and a semicolon on Windows (`;`).\n\nAn alternative to setting `PYTHONPATH` is to add `.pth` files in special\ndirectories of your Python installation(s). For instance, you could create\na file, say, `FlightGear-meta.pth`, containing a single line (with no\nspace at the beginning):\n\n /path/to/fgmeta/python3-flightgear/src\n\nIf you want the modules present in\n`/path/to/fgmeta/python3-flightgear/src` to be accessible to a particular\nPython interpreter (say, a Python\u00a03.8), simply put the `.pth` file in\n`/path/to/python-install-dir/lib/python3.8/site-packages/`. This can even\nbe a virtual environment if you want\u2014that is basically how `pip` installs\npackages in editable mode inside a venv. For the system Python\ninterpreters on Debian, you can put the `.pth` file in, e.g,\n`/usr/local/lib/python3.8/dist-packages/`. Note that you may add more\nlines to a `.pth` file in case you want to add other paths to the Python\ninterpreter's `sys.path`.\n\n## The scripts\n\nOnce you've done the above setup, the Python modules from\n`fgmeta/python3-flightgear/src` should be available to the chosen Python\ninterpreter. What about scripts that rely on these modules?\n\nMost scripts are declared in `python3-flightgear/pyproject.toml` and\nautomatically created by the `pip install` command from the \u201cRecommended\nmethod for development\u201d (remember: use `dir/bin/pip install` if you want\nthe installation to happen under the `dir` venv). There may be a few\nexceptions, like currently `catalog/update-catalog.py` which exists as a\nstandalone script in FGMeta. As long as the modules from\n`fgmeta/python3-flightgear/src` are installed for Python (i.e., accessible\nvia its `sys.path`), which the above methods ensure, such scripts will\nwork too.\n\nThe only remaining problem is therefore the following: if you used the\n\u201calternate way\u201d, you don't have the scripts that `pip install` would have\ncreated for you in the \u201crecommended way\u201d. However, these scripts are\ncurrently available as Python modules. For instance, the file\n`python3-flightgear/src/flightgear/meta/scripts/i18n/fg_extract_translatable_strings.py`\ncan be imported as a Python module. Example: the command\n\n python3 -m flightgear.meta.scripts.i18n.fg_extract_translatable_strings --help\n\nis equivalent to\n\n fg-extract-translatable-strings --help\n\nThis might be useful for one-off uses of the scripts like in Continuous\nIntegration, where one doesn't necessarily want to run `pip`: one could\nset `PYTHONPATH` and run the desired module(s) as above (the obvious\nalternative being to create a temporary venv and use the \u201crecommended\nway\u201d).\n\n## Running the unit tests\n\nOnce the modules in `python3-flightgear/src` are visible to Python\n(regardless of the method used), the unit tests of this package can be run\nwith:\n\n cd python3-flightgear\n python3 -m unittest\n\n(the second command is equivalent to `python3 -m unittest discover`; more\ndetails in `tests/README.md`).\n\n## Building the package\n\nIn case you want to build the package, you can do:\n\n cd python3-flightgear\n python3 -m build\n\nThis requires the Python `build` tool as explained in the\n[Python Packaging User Guide](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#packaging-your-project).\n",
"bugtrack_url": null,
"license": null,
"summary": "Tooling for the FlightGear flight simulator",
"version": "1.0.0a1",
"project_urls": {
"Homepage": "https://www.flightgear.org/",
"Issues": "https://gitlab.com/flightgear/fgmeta/-/issues",
"Repository": "https://gitlab.com/flightgear/fgmeta"
},
"split_keywords": [
"flightgear",
" flightgear",
" flight",
" simulator",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0874ea4c8c9b8fe84499b66c9c37c715c8b529bee338e13f450d6d55d3587b17",
"md5": "226ca51ec8ea5c70e2c67b49977b87d6",
"sha256": "666db3459fdd99b5bc340d91476634adc1f0f2cd521812fc22925292cd6ee6f8"
},
"downloads": -1,
"filename": "flightgear-1.0.0a1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "226ca51ec8ea5c70e2c67b49977b87d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75575,
"upload_time": "2025-07-20T19:07:54",
"upload_time_iso_8601": "2025-07-20T19:07:54.250066Z",
"url": "https://files.pythonhosted.org/packages/08/74/ea4c8c9b8fe84499b66c9c37c715c8b529bee338e13f450d6d55d3587b17/flightgear-1.0.0a1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "688baa902bc4411e62dc3def90fe87ed084b2672baf2e85b084a2b9a42389fd6",
"md5": "692da27b8cfef427e418007de0f07a30",
"sha256": "a4a87cd9869a326312c7f71688910dd5bd34210e29243341ca136c41e10b8c3c"
},
"downloads": -1,
"filename": "flightgear-1.0.0a1.tar.gz",
"has_sig": false,
"md5_digest": "692da27b8cfef427e418007de0f07a30",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 91125,
"upload_time": "2025-07-20T19:07:55",
"upload_time_iso_8601": "2025-07-20T19:07:55.572006Z",
"url": "https://files.pythonhosted.org/packages/68/8b/aa902bc4411e62dc3def90fe87ed084b2672baf2e85b084a2b9a42389fd6/flightgear-1.0.0a1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 19:07:55",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flightgear",
"gitlab_project": "fgmeta",
"lcname": "flightgear"
}
JSON