[](https://github.com/SETI/rms-textkernel/releases)
[](https://github.com/SETI/rms-textkernel/releases)
[](https://github.com/SETI/rms-textkernel/actions)
[](https://rms-textkernel.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/SETI/rms-textkernel)
<br />
[](https://pypi.org/project/rms-textkernel)
[](https://pypi.org/project/rms-textkernel)
[](https://pypi.org/project/rms-textkernel)
[](https://pypi.org/project/rms-textkernel)
<br />
[](https://github.com/SETI/rms-textkernel/commits/main/)
[](https://github.com/SETI/rms-textkernel/commits/main/)
[](https://github.com/SETI/rms-textkernel/commits/main/)
<br />
[](https://github.com/SETI/rms-textkernel/issues)
[](https://github.com/SETI/rms-textkernel/issues)
[](https://github.com/SETI/rms-textkernel/pulls)
[](https://github.com/SETI/rms-textkernel/pulls)
<br />
[](https://github.com/SETI/rms-textkernel/stargazers)
# Introduction
`textkernel` is a set of routines for parsing SPICE text kernels. This module
implements the complete syntax specification as discussed in the SPICE Kernel
Required Reading document, "kernel.req":
<https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/kernel.html>
`textkernel` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).
# Installation
The `textkernel` module is available via the `rms-textkernel` package on PyPI and can be
installed with:
```sh
pip install rms-textkernel
```
# Getting Started
The `textkernel` module provides two functions for reading text kernels:
- [`from_text`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.from_text):
Given a string representing the contents of a text kernel, return a dictionary of the values found.
- [`from_file`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.from_file):
Given the path to a text kernel, read the contents and return a dictionary of the values found.
and two functions for manipulating text kernels:
- [`continued_value`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.continued_value):
Interpret a list of strings as one or more continued strings.
- [`update_dict`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.update_dict):
Merge the contents of two text kernel dictionaries, preserving nested values.
Details of each function are available in the [module documentation](https://rms-textkernel.readthedocs.io/en/latest/module.html).
The simplest use case is as follows:
```python
import textkernel
tkdict = textkernel.from_file('path/to/kernel/file')
```
The returned dictionary `tkdict` is keyed by all the parameter names (on the left side of
an equal sign) in the text kernel, and each associated dictionary value is that found on
the right side. Values are Python ints, floats, strings, datetime objects, or lists of
one or more of these.
## Hierarchical Keys
For convenience, the returned dictionary adds additional "hierarchical" keys that provide
alternative access to the same values. Hierarchical keys are substrings from the original
parameter name, which return a sub-dictionary keyed by part or all of the remainder of
that parameter name.
Parameter names with a slash are split apart as if they represented components of a file
directory tree, so these are equivalent:
```python
tkdict["DELTET/EB"] == tkdict["DELTET"]["EB"]
```
When a body or frame ID is embedded inside a parameter name, it is extracted, converted
to integer, and used as a piece of the hierarchy, making these equivalent:
```python
tkdict["BODY399_POLE_RA"] == tkdict["BODY"][399]["POLE_RA"]
tkdict["SCLK01_MODULI_32"] == tkdict["SCLK"][-32]["01_MODULI"]
```
Leading and trailing underscores before and after the embedded numeric ID are stripped
from the hierarchical keys, as you can see in the examples above. Note also that the
components of the parameter name are re-ordered in the second example, so that the
second key is always the numeric ID.
When the name associated with a body or frame ID is known, that name can be used in the
place of the integer ID:
```python
tkdict["BODY"][399] == tkdict["BODY"]["EARTH"]
tkdict["FRAME"][10013] == tkdict["FRAME"]["IAU_EARTH"]
tkdict["SCLK"][-32] == tkdict["SCLK"]["VOYAGER 2"]
```
If a frame is uniquely or primarily associated with a particular central body, that
body's ID can also be used in place of the frame's ID:
```python
tkdict["FRAME"][399] == tkdict["FRAME"]["IAU_EARTH"]
```
Note that the "BODY" and "FRAME" dictionaries also have an additional entry keyed by "ID",
which returns the associated integer ID:
```python
tkdict["FRAME"][623]["ID"] = 623
tkdict["FRAME"]["IAU_SUTTUNGR"]["ID"] = 623
```
This ensures that you can look up a body or frame by name and readily obtain its ID.
# Contributing
Information on contributing to this package can be found in the
[Contributing Guide](https://github.com/SETI/rms-textkernel/blob/main/CONTRIBUTING.md).
# Links
- [Documentation](https://rms-textkernel.readthedocs.io)
- [Repository](https://github.com/SETI/rms-textkernel)
- [Issue tracker](https://github.com/SETI/rms-textkernel/issues)
- [PyPi](https://pypi.org/project/rms-textkernel)
# Licensing
This code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-textkernel/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "rms-textkernel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Robert S. French\" <rfrench@seti.org>",
"keywords": "spice, naif, jpl, space, geometry, ephemeris, text kernel",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6e/a7/57badb2432f70876d024f61206c6a55d6d42b67cb4a673488da07513ac2a/rms_textkernel-1.0.5.tar.gz",
"platform": null,
"description": "[](https://github.com/SETI/rms-textkernel/releases)\n[](https://github.com/SETI/rms-textkernel/releases)\n[](https://github.com/SETI/rms-textkernel/actions)\n[](https://rms-textkernel.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/SETI/rms-textkernel)\n<br />\n[](https://pypi.org/project/rms-textkernel)\n[](https://pypi.org/project/rms-textkernel)\n[](https://pypi.org/project/rms-textkernel)\n[](https://pypi.org/project/rms-textkernel)\n<br />\n[](https://github.com/SETI/rms-textkernel/commits/main/)\n[](https://github.com/SETI/rms-textkernel/commits/main/)\n[](https://github.com/SETI/rms-textkernel/commits/main/)\n<br />\n[](https://github.com/SETI/rms-textkernel/issues)\n[](https://github.com/SETI/rms-textkernel/issues)\n[](https://github.com/SETI/rms-textkernel/pulls)\n[](https://github.com/SETI/rms-textkernel/pulls)\n<br />\n\n[](https://github.com/SETI/rms-textkernel/stargazers)\n\n\n# Introduction\n\n`textkernel` is a set of routines for parsing SPICE text kernels. This module\nimplements the complete syntax specification as discussed in the SPICE Kernel\nRequired Reading document, \"kernel.req\":\n<https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/kernel.html>\n\n`textkernel` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).\n\n# Installation\n\nThe `textkernel` module is available via the `rms-textkernel` package on PyPI and can be\ninstalled with:\n\n```sh\npip install rms-textkernel\n```\n\n# Getting Started\n\nThe `textkernel` module provides two functions for reading text kernels:\n\n- [`from_text`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.from_text):\n Given a string representing the contents of a text kernel, return a dictionary of the values found.\n- [`from_file`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.from_file):\n Given the path to a text kernel, read the contents and return a dictionary of the values found.\n\nand two functions for manipulating text kernels:\n\n- [`continued_value`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.continued_value):\n Interpret a list of strings as one or more continued strings.\n- [`update_dict`](https://rms-textkernel.readthedocs.io/en/latest/module.html#textkernel.update_dict):\n Merge the contents of two text kernel dictionaries, preserving nested values.\n\nDetails of each function are available in the [module documentation](https://rms-textkernel.readthedocs.io/en/latest/module.html).\n\nThe simplest use case is as follows:\n\n```python\nimport textkernel\ntkdict = textkernel.from_file('path/to/kernel/file')\n```\n\nThe returned dictionary `tkdict` is keyed by all the parameter names (on the left side of\nan equal sign) in the text kernel, and each associated dictionary value is that found on\nthe right side. Values are Python ints, floats, strings, datetime objects, or lists of\none or more of these.\n\n## Hierarchical Keys\n\nFor convenience, the returned dictionary adds additional \"hierarchical\" keys that provide\nalternative access to the same values. Hierarchical keys are substrings from the original\nparameter name, which return a sub-dictionary keyed by part or all of the remainder of\nthat parameter name.\n\nParameter names with a slash are split apart as if they represented components of a file\ndirectory tree, so these are equivalent:\n\n```python\ntkdict[\"DELTET/EB\"] == tkdict[\"DELTET\"][\"EB\"]\n```\n\nWhen a body or frame ID is embedded inside a parameter name, it is extracted, converted\nto integer, and used as a piece of the hierarchy, making these equivalent:\n\n```python\ntkdict[\"BODY399_POLE_RA\"] == tkdict[\"BODY\"][399][\"POLE_RA\"]\ntkdict[\"SCLK01_MODULI_32\"] == tkdict[\"SCLK\"][-32][\"01_MODULI\"]\n```\n\nLeading and trailing underscores before and after the embedded numeric ID are stripped\nfrom the hierarchical keys, as you can see in the examples above. Note also that the\ncomponents of the parameter name are re-ordered in the second example, so that the\nsecond key is always the numeric ID.\n\nWhen the name associated with a body or frame ID is known, that name can be used in the\nplace of the integer ID:\n\n```python\ntkdict[\"BODY\"][399] == tkdict[\"BODY\"][\"EARTH\"]\ntkdict[\"FRAME\"][10013] == tkdict[\"FRAME\"][\"IAU_EARTH\"]\ntkdict[\"SCLK\"][-32] == tkdict[\"SCLK\"][\"VOYAGER 2\"]\n```\n\nIf a frame is uniquely or primarily associated with a particular central body, that\nbody's ID can also be used in place of the frame's ID:\n\n```python\ntkdict[\"FRAME\"][399] == tkdict[\"FRAME\"][\"IAU_EARTH\"]\n```\n\nNote that the \"BODY\" and \"FRAME\" dictionaries also have an additional entry keyed by \"ID\",\nwhich returns the associated integer ID:\n\n```python\ntkdict[\"FRAME\"][623][\"ID\"] = 623\ntkdict[\"FRAME\"][\"IAU_SUTTUNGR\"][\"ID\"] = 623\n```\n\nThis ensures that you can look up a body or frame by name and readily obtain its ID.\n\n# Contributing\n\nInformation on contributing to this package can be found in the\n[Contributing Guide](https://github.com/SETI/rms-textkernel/blob/main/CONTRIBUTING.md).\n\n# Links\n\n- [Documentation](https://rms-textkernel.readthedocs.io)\n- [Repository](https://github.com/SETI/rms-textkernel)\n- [Issue tracker](https://github.com/SETI/rms-textkernel/issues)\n- [PyPi](https://pypi.org/project/rms-textkernel)\n\n# Licensing\n\nThis code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-textkernel/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Routines for parsing SPICE text kernels",
"version": "1.0.5",
"project_urls": {
"Documentation": "https://rms-textkernel.readthedocs.io/en/latest",
"Homepage": "https://github.com/SETI/rms-textkernel",
"Issues": "https://github.com/SETI/rms-textkernel/issues",
"Repository": "https://github.com/SETI/rms-textkernel",
"Source": "https://github.com/SETI/rms-textkernel"
},
"split_keywords": [
"spice",
" naif",
" jpl",
" space",
" geometry",
" ephemeris",
" text kernel"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34377935e83c6fbeb1909991b4e4b6dc0ce431ced156249ed6515e1f8ebd5ca2",
"md5": "e5ee3e4613e93e559d2d3c5973d59a8e",
"sha256": "2b1d7c99c44d1d9cb1f89f63ed1f5f8999f1e5236cb3703c1932bc57ca1470d0"
},
"downloads": -1,
"filename": "rms_textkernel-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5ee3e4613e93e559d2d3c5973d59a8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43107,
"upload_time": "2024-12-16T20:41:45",
"upload_time_iso_8601": "2024-12-16T20:41:45.409673Z",
"url": "https://files.pythonhosted.org/packages/34/37/7935e83c6fbeb1909991b4e4b6dc0ce431ced156249ed6515e1f8ebd5ca2/rms_textkernel-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ea757badb2432f70876d024f61206c6a55d6d42b67cb4a673488da07513ac2a",
"md5": "5faef6692cdf8d3b6861eaec8a7b9f00",
"sha256": "1b767b320a5e739a74bd574d66d2d5b7517b3b67377adb6e301692ce58cad63a"
},
"downloads": -1,
"filename": "rms_textkernel-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "5faef6692cdf8d3b6861eaec8a7b9f00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 268103,
"upload_time": "2024-12-16T20:41:48",
"upload_time_iso_8601": "2024-12-16T20:41:48.786529Z",
"url": "https://files.pythonhosted.org/packages/6e/a7/57badb2432f70876d024f61206c6a55d6d42b67cb4a673488da07513ac2a/rms_textkernel-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 20:41:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SETI",
"github_project": "rms-textkernel",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "coverage",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "myst-parser",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "pyparsing",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "rms-julian",
"specs": []
},
{
"name": "sphinx",
"specs": []
},
{
"name": "sphinxcontrib-napoleon",
"specs": []
},
{
"name": "sphinx-rtd-theme",
"specs": []
}
],
"lcname": "rms-textkernel"
}
JSON
