===============================
pvl
===============================
.. image:: https://readthedocs.org/projects/pvl/badge/?version=latest
:target: https://pvl.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/planetarypy/pvl/workflows/Python%20Testing/badge.svg
:target: https://github.com/planetarypy/pvl/actions
.. image:: https://codecov.io/gh/planetarypy/pvl/branch/main/graph/badge.svg?token=uWqotcPTGR
:target: https://codecov.io/gh/planetarypy/pvl
:alt: Codecov coverage
.. image:: https://img.shields.io/pypi/v/pvl.svg?style=flat-square
:target: https://pypi.python.org/pypi/pvl
:alt: PyPI version
.. image:: https://img.shields.io/pypi/dm/pvl.svg?style=flat-square
:target: https://pypi.python.org/pypi/pvl
:alt: PyPI Downloads/month
.. image:: https://img.shields.io/conda/vn/conda-forge/pvl.svg
:target: https://anaconda.org/conda-forge/pvl
:alt: conda-forge version
.. image:: https://img.shields.io/conda/dn/conda-forge/pvl.svg
:target: https://anaconda.org/conda-forge/pvl
:alt: conda-forge downloads
Python implementation of a PVL (Parameter Value Language) library.
* Free software: BSD license
* Documentation: http://pvl.readthedocs.org.
* Support for Python 3.6 and higher (avaiable via pypi and conda).
* `PlanetaryPy`_ Affiliate Package.
PVL is a markup language, like JSON or YAML, commonly employed for
entries in the Planetary Data System used by NASA to archive
mission data, among other uses. This package supports both encoding
and decoding a variety of PVL 'flavors' including PVL itself, ODL,
`NASA PDS 3 Labels`_, and `USGS ISIS Cube Labels`_.
Installation
------------
Can either install with pip or with conda.
To install with pip, at the command line::
$ pip install pvl
Directions for installing with conda-forge:
Installing ``pvl`` from the conda-forge channel can be achieved by adding
conda-forge to your channels with::
conda config --add channels conda-forge
Once the conda-forge channel has been enabled, ``pvl`` can be installed with::
conda install pvl
It is possible to list all of the versions of ``pvl`` available on your platform
with::
conda search pvl --channel conda-forge
Basic Usage
-----------
``pvl`` exposes an API familiar to users of the standard library
``json`` module.
Decoding is primarily done through ``pvl.load()`` for file-like objects and
``pvl.loads()`` for strings::
>>> import pvl
>>> module = pvl.loads("""
... foo = bar
... items = (1, 2, 3)
... END
... """)
>>> print(module)
PVLModule([
('foo', 'bar')
('items', [1, 2, 3])
])
>>> print(module['foo'])
bar
There is also a ``pvl.loadu()`` to which you can provide the URL of a file that you would normally provide to
``pvl.load()``.
You may also use ``pvl.load()`` to read PVL text directly from an image_ that begins with PVL text::
>>> import pvl
>>> label = pvl.load('tests/data/pattern.cub')
>>> print(label)
PVLModule([
('IsisCube',
{'Core': {'Dimensions': {'Bands': 1,
'Lines': 90,
'Samples': 90},
'Format': 'Tile',
'Pixels': {'Base': 0.0,
'ByteOrder': 'Lsb',
'Multiplier': 1.0,
'Type': 'Real'},
'StartByte': 65537,
'TileLines': 128,
'TileSamples': 128}})
('Label', PVLObject([
('Bytes', 65536)
]))
])
>>> print(label['IsisCube']['Core']['StartByte'])
65537
Similarly, encoding Python objects as PVL text is done through
``pvl.dump()`` and ``pvl.dumps()``::
>>> import pvl
>>> print(pvl.dumps({
... 'foo': 'bar',
... 'items': [1, 2, 3]
... }))
FOO = bar
ITEMS = (1, 2, 3)
END
<BLANKLINE>
``pvl.PVLModule`` objects may also be pragmatically built up
to control the order of parameters as well as duplicate keys::
>>> import pvl
>>> module = pvl.PVLModule({'foo': 'bar'})
>>> module.append('items', [1, 2, 3])
>>> print(pvl.dumps(module))
FOO = bar
ITEMS = (1, 2, 3)
END
<BLANKLINE>
A ``pvl.PVLModule`` is a ``dict``-like container that preserves
ordering as well as allows multiple values for the same key. It provides
similar semantics to a ``list`` of key/value ``tuples`` but
with ``dict``-style access::
>>> import pvl
>>> module = pvl.PVLModule([
... ('foo', 'bar'),
... ('items', [1, 2, 3]),
... ('foo', 'remember me?'),
... ])
>>> print(module['foo'])
bar
>>> print(module.getall('foo'))
['bar', 'remember me?']
>>> print(module.items())
ItemsView(PVLModule([
('foo', 'bar')
('items', [1, 2, 3])
('foo', 'remember me?')
]))
>>> print(pvl.dumps(module))
FOO = bar
ITEMS = (1, 2, 3)
FOO = 'remember me?'
END
<BLANKLINE>
However, there are some aspects to the default ``pvl.PVLModule`` that are not entirely
aligned with the modern Python 3 expectations of a Mapping object. If you would like
to experiment with a more Python-3-ic object, you could instantiate a
``pvl.collections.PVLMultiDict`` object, or ``import pvl.new as pvl`` in your code
to have the loaders return objects of this type (and then easily switch back by just
changing the import statement). To learn more about how PVLMultiDict is different
from the existing OrderedMultiDict that PVLModule is derived from, please read the
new PVLMultiDict documentation.
The intent is for the loaders (``pvl.load()``, ``pvl.loads()``, and ``pvl.loadu()``)
to be permissive, and attempt to parse as wide a variety of PVL text as
possible, including some kinds of 'broken' PVL text.
On the flip side, when dumping a Python object to PVL text (via
``pvl.dumps()`` and ``pvl.dump()``), the library will default
to writing PDS3-Standards-compliant PVL text, which in some ways
is the most restrictive, but the most likely version of PVL text
that you need if you're writing it out (this is different from
pre-1.0 versions of ``pvl``).
You can change this behavior by giving different parameters to the
loaders and dumpers that define the grammar of the PVL text that
you're interested in, as well as custom parsers, decoders, and
encoders.
For more information on custom serilization and deseralization see the
`full documentation`_.
Contributing
------------
Feedback, issues, and contributions are always gratefully welcomed. See the
`contributing guide`_ for details on how to help and setup a development
environment.
.. _PlanetaryPy: https://planetarypy.org
.. _USGS ISIS Cube Labels: http://isis.astrogeology.usgs.gov/
.. _NASA PDS 3 Labels: https://pds.nasa.gov
.. _image: https://github.com/planetarypy/pvl/raw/master/tests/data/pattern.cub
.. _full documentation: http://pvl.readthedocs.org
.. _contributing guide: https://github.com/planetarypy/pvl/blob/master/CONTRIBUTING.rst
=========
History
=========
All notable changes to this project will be documented in this file.
The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
When updating this file, please add an entry for your change under
`Not Yet Released`_ and one of the following headings:
- Added - for new features.
- Changed - for changes in existing functionality.
- Deprecated - for soon-to-be removed features.
- Removed - for now removed features.
- Fixed - for any bug fixes.
- Security - in case of vulnerabilities.
If the heading does not yet exist under `Not Yet Released`_, then add it
as a 3rd level heading, underlined with pluses (see examples below).
When preparing for a public release add a new 2nd level heading,
underlined with dashes under `Not Yet Released`_ with the version number
and the release date, in year-month-day format (see examples below).
Not Yet Released
----------------
1.3.2 (2022-02-05)
------------------
Fixed
+++++
* The parser was requesting the next token after an end-statement, even
though nothing was done with this token (in the future it could
be a comment that should be processed). In the very rare case
where all of the "data" bytes in a file with an attached PVL label
(like a .IMG or .cub file) actually convert to UTF with no
whitespace characters, that next token will take an unacceptable
amount of time to return, if it does at all. The parser now does
not request additional tokens once an end-statement is identified
(Issue 104).
1.3.1 (2022-02-05)
------------------
Fixed
+++++
* Deeply nested Aggregation Blocks (Object or Group) which had mis-matched
Block Names should now properly result in LexerErrors instead of
resulting in StopIteration Exceptions (Issue 100).
* The default "Omni" parsing strategy, now considers the ASCII NULL character
("\0") a "reserved character." The practical effect is that the
ASCII NULL can not be in parameter names or unquoted strings (but
would still be successfully parsed in quoted strings). This means
that PVL-text that might have incorrectly used ASCII NULLs as
delimiters will once again be consumed by our omnivorous parser
(Issue 98).
1.3.0 (2021-09-10)
------------------
Added
+++++
* pvl.collections.Quantity objects now have __int__() and __float__()
functions that will return the int and float versions of their
.value parameter to facilitate numeric operations with Quantity
objects (Issue 91).
* pvl.load() now has an `encoding=` parameter that is identical in usage
to the parameter passed to `open()`, and will attempt to decode the whole
file as if it had been encoded thusly. If it encounters a decoding error,
it will fall back to decoding the bytes one at a time as ASCII text (Issue 93).
Fixed
+++++
* If the PVL-text contained characters beyond the set allowed by the
PVL specification, the OmniGrammar would refuse to parse them.
This has been fixed to allow any valid character to be parsed,
so that if there are weird UTF characters in the PVL-text, you'll get
those weird UTF characters in the returned dict-like. When the
stricter PVL, ODL, or PDS3 dialects are used to "load" PVL-text,
they will properly fail to parse this text (Issue 93).
* Empty parameters inside groups or objects (but not at the end), would
cause the default "Omni" parsing strategy to go into an infinite
loop. Empty parameters in PVL, ODL, and PDS3 continue to not be
allowed (Issue 95).
1.2.1 (2021-05-31)
------------------
Added
+++++
* So many tests, increased coverage by about 10%.
Fixed
+++++
* Attempting to import `pvl.new` without *multidict* being available,
will now properly yield an ImportError.
* The `dump()` and `dumps()` functions now properly overwritten in `pvl.new`.
* All encoders that descended from PVLEncoder didn't properly have group_class and
object_class arguments to their constructors, now they do.
* The `char_allowed()` function in grammar objects now raises a more useful ValueError
than just a generic Exception.
* The new `collections.PVLMultiDict` wasn't correctly inserting Mapping objects with
the `insert_before()` and `insert_after()` methods.
* The `token.Token` class's `__index__()` function didn't always properly return an
index.
* The `token.Token` class's `__float__()` function would return int objects if the
token could be converted to int. Now always returns floats.
1.2.0 (2021-03-27)
------------------
Added
+++++
* Added a default_timezone parameter to grammar objects so that they could
both communicate whether they had a default timezone (if not None),
and what it was.
* Added a pvl.grammar.PDSGrammar class that specifies the default UTC
time offset.
* Added a pvl.decoder.PDSLabelDecoder class that properly enforces only
milisecond time precision (not microsecond as ODL allows), and does
not allow times with a +HH:MM timezone specifier. It does assume
any time without a timezone specifier is a UTC time.
* Added a ``real_cls`` parameter to the decoder classes, so that users can specify
an arbitrary type with which real numbers in the PVL-text could be returned in
the dict-like from the loaders (defaults to ``float`` as you'd expect).
* The encoders now support a broader range of real types to complement the decoders.
Changed
+++++++
* Improved some build and test functionality.
* Moved the is_identifier() static function from the ODLEncoder to the ODLDecoder
where it probably should have always been.
Fixed
+++++
* Very long Python ``str`` objects that otherwise qualified as ODL/PDS3 Symbol Strings,
would get written out with single-quotes, but they would then be split across lines
via the formatter, so they should be written as Text Strings with double-quotes.
Better protections have been put in place.
* pvl.decoder.ODLDecoder now will return both "aware" and "naive"
datetime objects (as appropriate) since "local" times without a
timezone are allowed under ODL.
* pvl.decoder.ODLDecoder will now properly reject any unquoted string
that does not parse as an ODL Identifier.
* pvl.decoder.ODLDecoder will raise an exception if there is a seconds value
of 60 (which the PVLDecoder allows)
* pvl.encoder.ODLEncoder will raise an exception if given a "naive" time
object.
* pvl.encoder.PDSLabelEncoder will now properly raise an exception if
a time or datetime object cannot be represented with only milisecond
precision.
1.1.0 (2020-12-04)
------------------
Added
+++++
* Modified `pvl_validate` to more robustly deal with errors, and also provide
more error-reporting via `-v` and `-vv`.
* Modified ISISGrammar so that it can parse comments that begin with an octothorpe (#).
Fixed
+++++
* Altered documentation in grammar.py that was incorrectly indicating that
there were parameters that could be passed on object initiation that would
alter how those objects behaved.
1.0.1 (2020-09-21)
------------------
Fixed
+++++
* The PDSLabelEncoder was improperly raising an exception if the Python datetime
object to encode had a tzinfo component that had zero offset from UTC.
1.0.0 (2020-08-23)
------------------
This production version of the pvl library consists of significant
API and functionality changes from the 0.x version that has been
in use for 5 years (a credit to Trevor Olson's skills). The
documentation has been significantly upgraded, and various granular
changes over the 10 alpha versions of 1.0.0 over the last 8 months
are detailed in their entries below. However, here is a high-level
overview of what changed from the 0.x version:
Added
+++++
* ``pvl.load()`` and ``pvl.dump()`` take all of the arguments that they could take
before (string containing a filename, byte streams, etc.), but now also accept any
``os.PathLike`` object, or even an already-opened file object.
* ``pvl.loadu()`` function will load PVL text from URLs.
* Utility programs `pvl_validate` and `pvl_translate` were added, please see
the "Utility Programs" section of the documentation for more information.
* The library can now parse and encode PVL Values with Units expressions
with third-party quantity objects like `astropy.units.Quantity` and `pint.Quantity`.
Please see the "Quantities: Values and Units" section of the documentation.
* Implemented a new PVLMultiDict (optional, needs 3rd party multidict library) which
which has more pythonic behaviors than the existing OrderedMultiDict. Experiment
with getting it returned by the loaders by altering your import statement to
``import pvl.new as pvl`` and then using the loaders as usual to get the new object
returned to you.
Changed
+++++++
* Only guaranteed to work with Python 3.6 and above.
* Rigorously implemented the three dialects of PVL text: PVL itself,
ODL, and the PDS3 Label Standard. There is a fourth de-facto
dialect, that of ISIS cube labels that is also handled. Please see
the "Standards & Specifications" section of the documentation.
* There is now a default dialect for the dump functions: the PDS3 Label Standard.
This is different and more strict than before, but other output dialects are
possible. Please see the "Writing out PVL text" section in the documentation
for more information, and how to enable an output similar to the 0.x output.
* There are now ``pvl.collections`` and ``pvl.exceptions`` modules. There was previously
an internal ``pvl._collections`` module, and the exception classes were scattered through
the other modules.
Fixed
+++++
* All ``datetime.time`` and ``datetime.datetime`` objects returned from the loaders
are now timezone "aware." Previously some were and some were not.
* Functionality to correctly parse dash (-) continuation lines in ISIS output is
now supported.
* The library now properly parses quoted strings that include backslashes.
Deprecated
++++++++++
* The `pvl.collections.Units` object is deprecated in favor of
the new ``pvl.collections.Quantity`` object (really a name-only change, no functionality
difference).
1.0.0-alpha.9 (2020-08-18)
--------------------------
* Minor addition to pvl.collections.MutableMappingSequence.
* Implemented PVLMultiDict which is based on the 3rd Party
`multidict.MultiDict` object as an option to use instead
of the default OrderedMultiDict. The new PVLMultiDict
is better aligned with the Python 3 way that Mapping
objects behave.
* Enhanced the existing OrderedMultiDict with some functionality
that extends its behavior closer to the Python 3 ideal, and
inserted warnings about how the retained non-Python-3
behaviors might be removed at the next major patch.
* Implemented pvl.new that can be included for those that wish
to try out what getting the new PVLMultiDict returned from
the loaders might be like by just changing an import statement.
1.0.0-alpha.8 (2020-08-01)
--------------------------
* Renamed the _collections module to just collections.
* Renamed the Units class to Quantity (Units remains, but has a deprecation warning).
* Defined a new ABC: pvl.collections.MutableMappingSequence
* More detail for these changes can be found in Issue #62.
1.0.0-alpha.7 (2020-07-29)
--------------------------
* Created a new exceptions.py module and grouped all pvl Exceptions
there. Addresses #58
* Altered the message that LexerError emits to provide context
around the character that caused the error.
* Added bump2version configuration file.
1.0.0-alpha.6 (2020-07-27)
--------------------------
* Enforced that all datetime.time and datetime.datetime objects
returned should be timezone "aware." This breaks 0.x functionality
where some were and some weren't. Addresses #57.
1.0.0-alpha.5 (2020-05-30)
--------------------------
* ISIS creates PVL text with unquoted plus signs ("+"), needed to adjust
the ISISGrammar and OmniGrammar objects to parse this properly (#59).
* In the process of doing so, realized that we have some classes that
optionally take a grammar and a decoder, and if they aren't given, to default.
However, a decoder *has* a grammar object, so if a grammar isn't provided, but
a decoder is, the grammar should be taken from the decoder, otherwise you
could get confusing behavior.
* Updated pvl_validate to be explicit about these arguments.
* Added a --version argument to both pvl_translate and pvl_validate.
1.0.0.-alpha.4 (2020-05-29)
---------------------------
* Added the pvl.loadu() function as a convenience function to load PVL text from
URLs.
1.0.0-alpha.3 (2020-05-28)
--------------------------
* Implemented tests in tox and Travis for Python 3.8, and discovered a bug
that we fixed (#54).
1.0.0-alpha.2 (2020-04-18)
--------------------------
* The ability to deal with 3rd-party 'quantity' objects like astropy.units.Quantity
and pint.Quantity was added and documented, addresses #22.
1.0.0-alpha.1 (2020-04-17)
--------------------------
This is a bugfix on 1.0.0-alpha to properly parse scientific notation
and deal with properly catching an error.
1.0.0-alpha (winter 2019-2020)
------------------------------
This is the alpha version of release 1.0.0 for pvl, and the items
here and in other 'alpha' entries may be consolidated when 1.0.0
is released. This work is categorized as 1.0.0-alpha because
backwards-incompatible changes are being introduced to the codebase.
* Refactored code so that it will no longer support Python 2,
and is only guaranteed to work with Python 3.6 and above.
* Rigorously implemented the three dialects of PVL text: PVL itself,
ODL, and the PDS3 Label Standard. There is a fourth de-facto
dialect, that of ISIS cube labels that is also handled. These
dialects each have their own grammars, parsers, decoders, and
encoders, and there are also some 'Omni' versions of same that
handle the widest possible range of PVL text.
* When parsing via the loaders, ``pvl`` continues to consume as
wide a variety of PVL text as is reasonably possible, just like
always. However, now when encoding via the dumpers, ``pvl`` will
default to writing out PDS3 Label Standard format PVL text, one
of the strictest dialects, but other options are available. This
behavior is different from the pre-1.0 version, which wrote out
more generic PVL text.
* Removed the dependency on the ``six`` library that provided Python 2
compatibility.
* Removed the dependency on the ``pytz`` library that provided 'timezone'
support, as that functionality is replaced with the Standard Library's
``datetime`` module.
* The private ``pvl/_numbers.py`` file was removed, as its capability is now
accomplished with the Python Standard Library.
* The private ``pvl/_datetimes.py`` file was removed, as its capability is now
accomplished with the Standard Library's ``datetime`` module.
* the private ``pvl/_strings.py`` file was removed, as its capabilities are now
mostly replaced with the new grammar module and some functions in other new
modules.
* Internally, the library is now working with string objects, not byte literals,
so the ``pvl/stream.py`` module is no longer needed.
* Added an optional dependency on the 3rd party ``dateutil`` library, to parse
more exotic date and time formats. If this library is not present, the
``pvl`` library will gracefully fall back to not parsing more exotic
formats.
* Implmented a more formal approach to parsing PVL text: The properties
of the PVL language are represented by a grammar object. A string is
broken into tokens by the lexer function. Those tokens are parsed by a
parser object, and when a token needs to be converted to a Python object,
a decoder object does that job. When a Python object must be converted to
PVL text, an encoder object does that job.
* Since the tests in ``tests/test_decoder.py`` and ``tests/test_encoder.py``
were really just exercising the loader and dumper functions, those tests were
moved to ``tests/test_pvl.py``, but all still work (with light modifications for
the new defaults). Unit tests were added for most of the new classes and
functions. All docstring tests now also pass doctest testing and are now
included in the ``make test`` target.
* Functionality to correctly parse dash (-) continuation lines written by ISIS
as detailed in #34 is implemented and tested.
* Functionality to use ``pathlib.Path`` objects for ``pvl.load()`` and
``pvl.dump()`` as requested in #20 and #31 is implemented and tested.
* Functionality to accept already-opened file objects that were opened in
'r' mode or 'rb' mode as alluded to in #6 is implemented and tested.
* The library now properly parses quoted strings that include backslashes
as detailed in #33.
* Utility programs pvl_validate and pvl_translate were added.
* Documentation was updated and expanded.
0.3.0 (2017-06-28)
------------------
* Create methods to add items to the label
* Give user option to allow the parser to succeed in parsing broken labels
0.2.0 (2015-08-13)
------------------
* Drastically increase test coverage.
* Lots of bug fixes.
* Add Cube and PDS encoders.
* Cleanup README.
* Use pvl specification terminology.
* Added element access by index and slice.
0.1.1 (2015-06-01)
------------------
* Fixed issue with reading Pancam PDS Products.
0.1.0 (2015-05-30)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/planetarypy/pvl",
"name": "pvl",
"maintainer": "Ross Beyer",
"docs_url": null,
"requires_python": "",
"maintainer_email": "rbeyer@rossbeyer.net",
"keywords": "pvl",
"author": "The PlanetaryPy Developers",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/51/20/63c4e77d106de29e59fe5d1b123de7c61242300b2315c2a57630022a5bf5/pvl-1.3.2.tar.gz",
"platform": null,
"description": "===============================\npvl\n===============================\n\n.. image:: https://readthedocs.org/projects/pvl/badge/?version=latest\n :target: https://pvl.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://github.com/planetarypy/pvl/workflows/Python%20Testing/badge.svg\n :target: https://github.com/planetarypy/pvl/actions\n\n.. image:: https://codecov.io/gh/planetarypy/pvl/branch/main/graph/badge.svg?token=uWqotcPTGR\n :target: https://codecov.io/gh/planetarypy/pvl\n :alt: Codecov coverage\n\n\n.. image:: https://img.shields.io/pypi/v/pvl.svg?style=flat-square\n :target: https://pypi.python.org/pypi/pvl\n :alt: PyPI version\n\n.. image:: https://img.shields.io/pypi/dm/pvl.svg?style=flat-square\n :target: https://pypi.python.org/pypi/pvl\n :alt: PyPI Downloads/month\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/pvl.svg\n :target: https://anaconda.org/conda-forge/pvl\n :alt: conda-forge version\n\n.. image:: https://img.shields.io/conda/dn/conda-forge/pvl.svg\n :target: https://anaconda.org/conda-forge/pvl\n :alt: conda-forge downloads\n\n\nPython implementation of a PVL (Parameter Value Language) library.\n\n* Free software: BSD license\n* Documentation: http://pvl.readthedocs.org.\n* Support for Python 3.6 and higher (avaiable via pypi and conda).\n* `PlanetaryPy`_ Affiliate Package.\n\nPVL is a markup language, like JSON or YAML, commonly employed for\nentries in the Planetary Data System used by NASA to archive\nmission data, among other uses. This package supports both encoding\nand decoding a variety of PVL 'flavors' including PVL itself, ODL,\n`NASA PDS 3 Labels`_, and `USGS ISIS Cube Labels`_.\n\n\nInstallation\n------------\n\nCan either install with pip or with conda.\n\nTo install with pip, at the command line::\n\n $ pip install pvl\n\nDirections for installing with conda-forge:\n\nInstalling ``pvl`` from the conda-forge channel can be achieved by adding\nconda-forge to your channels with::\n\n conda config --add channels conda-forge\n\n\nOnce the conda-forge channel has been enabled, ``pvl`` can be installed with::\n\n conda install pvl\n\nIt is possible to list all of the versions of ``pvl`` available on your platform\nwith::\n\n conda search pvl --channel conda-forge\n\n\nBasic Usage\n-----------\n\n``pvl`` exposes an API familiar to users of the standard library\n``json`` module.\n\nDecoding is primarily done through ``pvl.load()`` for file-like objects and\n``pvl.loads()`` for strings::\n\n >>> import pvl\n >>> module = pvl.loads(\"\"\"\n ... foo = bar\n ... items = (1, 2, 3)\n ... END\n ... \"\"\")\n >>> print(module)\n PVLModule([\n ('foo', 'bar')\n ('items', [1, 2, 3])\n ])\n >>> print(module['foo'])\n bar\n\nThere is also a ``pvl.loadu()`` to which you can provide the URL of a file that you would normally provide to\n``pvl.load()``.\n\nYou may also use ``pvl.load()`` to read PVL text directly from an image_ that begins with PVL text::\n\n >>> import pvl\n >>> label = pvl.load('tests/data/pattern.cub')\n >>> print(label)\n PVLModule([\n ('IsisCube',\n {'Core': {'Dimensions': {'Bands': 1,\n 'Lines': 90,\n 'Samples': 90},\n 'Format': 'Tile',\n 'Pixels': {'Base': 0.0,\n 'ByteOrder': 'Lsb',\n 'Multiplier': 1.0,\n 'Type': 'Real'},\n 'StartByte': 65537,\n 'TileLines': 128,\n 'TileSamples': 128}})\n ('Label', PVLObject([\n ('Bytes', 65536)\n ]))\n ])\n >>> print(label['IsisCube']['Core']['StartByte'])\n 65537\n\n\nSimilarly, encoding Python objects as PVL text is done through\n``pvl.dump()`` and ``pvl.dumps()``::\n\n >>> import pvl\n >>> print(pvl.dumps({\n ... 'foo': 'bar',\n ... 'items': [1, 2, 3]\n ... }))\n FOO = bar\n ITEMS = (1, 2, 3)\n END\n <BLANKLINE>\n\n``pvl.PVLModule`` objects may also be pragmatically built up\nto control the order of parameters as well as duplicate keys::\n\n >>> import pvl\n >>> module = pvl.PVLModule({'foo': 'bar'})\n >>> module.append('items', [1, 2, 3])\n >>> print(pvl.dumps(module))\n FOO = bar\n ITEMS = (1, 2, 3)\n END\n <BLANKLINE>\n\nA ``pvl.PVLModule`` is a ``dict``-like container that preserves\nordering as well as allows multiple values for the same key. It provides\nsimilar semantics to a ``list`` of key/value ``tuples`` but \nwith ``dict``-style access::\n\n >>> import pvl\n >>> module = pvl.PVLModule([\n ... ('foo', 'bar'),\n ... ('items', [1, 2, 3]),\n ... ('foo', 'remember me?'),\n ... ])\n >>> print(module['foo'])\n bar\n >>> print(module.getall('foo'))\n ['bar', 'remember me?']\n >>> print(module.items())\n ItemsView(PVLModule([\n ('foo', 'bar')\n ('items', [1, 2, 3])\n ('foo', 'remember me?')\n ]))\n >>> print(pvl.dumps(module))\n FOO = bar\n ITEMS = (1, 2, 3)\n FOO = 'remember me?'\n END\n <BLANKLINE>\n\nHowever, there are some aspects to the default ``pvl.PVLModule`` that are not entirely\naligned with the modern Python 3 expectations of a Mapping object. If you would like\nto experiment with a more Python-3-ic object, you could instantiate a\n``pvl.collections.PVLMultiDict`` object, or ``import pvl.new as pvl`` in your code\nto have the loaders return objects of this type (and then easily switch back by just\nchanging the import statement). To learn more about how PVLMultiDict is different\nfrom the existing OrderedMultiDict that PVLModule is derived from, please read the\nnew PVLMultiDict documentation.\n\nThe intent is for the loaders (``pvl.load()``, ``pvl.loads()``, and ``pvl.loadu()``)\nto be permissive, and attempt to parse as wide a variety of PVL text as\npossible, including some kinds of 'broken' PVL text.\n\nOn the flip side, when dumping a Python object to PVL text (via\n``pvl.dumps()`` and ``pvl.dump()``), the library will default\nto writing PDS3-Standards-compliant PVL text, which in some ways\nis the most restrictive, but the most likely version of PVL text\nthat you need if you're writing it out (this is different from\npre-1.0 versions of ``pvl``).\n\nYou can change this behavior by giving different parameters to the\nloaders and dumpers that define the grammar of the PVL text that\nyou're interested in, as well as custom parsers, decoders, and\nencoders.\n\nFor more information on custom serilization and deseralization see the\n`full documentation`_.\n\n\nContributing\n------------\n\nFeedback, issues, and contributions are always gratefully welcomed. See the\n`contributing guide`_ for details on how to help and setup a development\nenvironment.\n\n\n.. _PlanetaryPy: https://planetarypy.org\n.. _USGS ISIS Cube Labels: http://isis.astrogeology.usgs.gov/\n.. _NASA PDS 3 Labels: https://pds.nasa.gov\n.. _image: https://github.com/planetarypy/pvl/raw/master/tests/data/pattern.cub\n.. _full documentation: http://pvl.readthedocs.org\n.. _contributing guide: https://github.com/planetarypy/pvl/blob/master/CONTRIBUTING.rst\n\n\n\n\n=========\n History\n=========\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,\nand this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.\n\nWhen updating this file, please add an entry for your change under\n`Not Yet Released`_ and one of the following headings:\n\n- Added - for new features.\n- Changed - for changes in existing functionality.\n- Deprecated - for soon-to-be removed features.\n- Removed - for now removed features.\n- Fixed - for any bug fixes.\n- Security - in case of vulnerabilities.\n\nIf the heading does not yet exist under `Not Yet Released`_, then add it\nas a 3rd level heading, underlined with pluses (see examples below).\n\nWhen preparing for a public release add a new 2nd level heading,\nunderlined with dashes under `Not Yet Released`_ with the version number\nand the release date, in year-month-day format (see examples below).\n\n\nNot Yet Released\n----------------\n\n\n1.3.2 (2022-02-05)\n------------------\n\nFixed\n+++++\n* The parser was requesting the next token after an end-statement, even\n though nothing was done with this token (in the future it could\n be a comment that should be processed). In the very rare case\n where all of the \"data\" bytes in a file with an attached PVL label\n (like a .IMG or .cub file) actually convert to UTF with no\n whitespace characters, that next token will take an unacceptable\n amount of time to return, if it does at all. The parser now does\n not request additional tokens once an end-statement is identified\n (Issue 104).\n\n\n1.3.1 (2022-02-05)\n------------------\n\nFixed\n+++++\n* Deeply nested Aggregation Blocks (Object or Group) which had mis-matched\n Block Names should now properly result in LexerErrors instead of\n resulting in StopIteration Exceptions (Issue 100).\n\n* The default \"Omni\" parsing strategy, now considers the ASCII NULL character\n (\"\\0\") a \"reserved character.\" The practical effect is that the\n ASCII NULL can not be in parameter names or unquoted strings (but\n would still be successfully parsed in quoted strings). This means\n that PVL-text that might have incorrectly used ASCII NULLs as\n delimiters will once again be consumed by our omnivorous parser\n (Issue 98).\n\n\n1.3.0 (2021-09-10)\n------------------\n\nAdded\n+++++\n* pvl.collections.Quantity objects now have __int__() and __float__()\n functions that will return the int and float versions of their\n .value parameter to facilitate numeric operations with Quantity\n objects (Issue 91).\n* pvl.load() now has an `encoding=` parameter that is identical in usage\n to the parameter passed to `open()`, and will attempt to decode the whole\n file as if it had been encoded thusly. If it encounters a decoding error,\n it will fall back to decoding the bytes one at a time as ASCII text (Issue 93).\n\nFixed\n+++++\n* If the PVL-text contained characters beyond the set allowed by the\n PVL specification, the OmniGrammar would refuse to parse them.\n This has been fixed to allow any valid character to be parsed,\n so that if there are weird UTF characters in the PVL-text, you'll get\n those weird UTF characters in the returned dict-like. When the\n stricter PVL, ODL, or PDS3 dialects are used to \"load\" PVL-text,\n they will properly fail to parse this text (Issue 93).\n* Empty parameters inside groups or objects (but not at the end), would\n cause the default \"Omni\" parsing strategy to go into an infinite\n loop. Empty parameters in PVL, ODL, and PDS3 continue to not be\n allowed (Issue 95).\n\n\n1.2.1 (2021-05-31)\n------------------\n\nAdded\n+++++\n* So many tests, increased coverage by about 10%.\n\nFixed\n+++++\n* Attempting to import `pvl.new` without *multidict* being available,\n will now properly yield an ImportError.\n* The `dump()` and `dumps()` functions now properly overwritten in `pvl.new`.\n* All encoders that descended from PVLEncoder didn't properly have group_class and\n object_class arguments to their constructors, now they do.\n* The `char_allowed()` function in grammar objects now raises a more useful ValueError\n than just a generic Exception.\n* The new `collections.PVLMultiDict` wasn't correctly inserting Mapping objects with\n the `insert_before()` and `insert_after()` methods.\n* The `token.Token` class's `__index__()` function didn't always properly return an\n index.\n* The `token.Token` class's `__float__()` function would return int objects if the\n token could be converted to int. Now always returns floats.\n\n\n1.2.0 (2021-03-27)\n------------------\n\nAdded\n+++++\n* Added a default_timezone parameter to grammar objects so that they could\n both communicate whether they had a default timezone (if not None),\n and what it was.\n* Added a pvl.grammar.PDSGrammar class that specifies the default UTC\n time offset.\n* Added a pvl.decoder.PDSLabelDecoder class that properly enforces only\n milisecond time precision (not microsecond as ODL allows), and does\n not allow times with a +HH:MM timezone specifier. It does assume\n any time without a timezone specifier is a UTC time.\n* Added a ``real_cls`` parameter to the decoder classes, so that users can specify\n an arbitrary type with which real numbers in the PVL-text could be returned in\n the dict-like from the loaders (defaults to ``float`` as you'd expect).\n* The encoders now support a broader range of real types to complement the decoders.\n\nChanged\n+++++++\n* Improved some build and test functionality.\n* Moved the is_identifier() static function from the ODLEncoder to the ODLDecoder\n where it probably should have always been.\n\n\nFixed\n+++++\n* Very long Python ``str`` objects that otherwise qualified as ODL/PDS3 Symbol Strings,\n would get written out with single-quotes, but they would then be split across lines\n via the formatter, so they should be written as Text Strings with double-quotes.\n Better protections have been put in place.\n* pvl.decoder.ODLDecoder now will return both \"aware\" and \"naive\"\n datetime objects (as appropriate) since \"local\" times without a\n timezone are allowed under ODL.\n* pvl.decoder.ODLDecoder will now properly reject any unquoted string\n that does not parse as an ODL Identifier.\n* pvl.decoder.ODLDecoder will raise an exception if there is a seconds value\n of 60 (which the PVLDecoder allows)\n* pvl.encoder.ODLEncoder will raise an exception if given a \"naive\" time\n object.\n* pvl.encoder.PDSLabelEncoder will now properly raise an exception if\n a time or datetime object cannot be represented with only milisecond\n precision.\n\n\n1.1.0 (2020-12-04)\n------------------\n\nAdded\n+++++\n* Modified `pvl_validate` to more robustly deal with errors, and also provide\n more error-reporting via `-v` and `-vv`.\n* Modified ISISGrammar so that it can parse comments that begin with an octothorpe (#).\n\nFixed\n+++++\n* Altered documentation in grammar.py that was incorrectly indicating that\n there were parameters that could be passed on object initiation that would\n alter how those objects behaved.\n\n\n1.0.1 (2020-09-21)\n------------------\n\nFixed\n+++++\n* The PDSLabelEncoder was improperly raising an exception if the Python datetime\n object to encode had a tzinfo component that had zero offset from UTC.\n\n\n1.0.0 (2020-08-23)\n------------------\nThis production version of the pvl library consists of significant\nAPI and functionality changes from the 0.x version that has been\nin use for 5 years (a credit to Trevor Olson's skills). The\ndocumentation has been significantly upgraded, and various granular\nchanges over the 10 alpha versions of 1.0.0 over the last 8 months\nare detailed in their entries below. However, here is a high-level\noverview of what changed from the 0.x version:\n\nAdded\n+++++\n* ``pvl.load()`` and ``pvl.dump()`` take all of the arguments that they could take\n before (string containing a filename, byte streams, etc.), but now also accept any\n ``os.PathLike`` object, or even an already-opened file object.\n* ``pvl.loadu()`` function will load PVL text from URLs.\n* Utility programs `pvl_validate` and `pvl_translate` were added, please see\n the \"Utility Programs\" section of the documentation for more information.\n* The library can now parse and encode PVL Values with Units expressions\n with third-party quantity objects like `astropy.units.Quantity` and `pint.Quantity`.\n Please see the \"Quantities: Values and Units\" section of the documentation.\n* Implemented a new PVLMultiDict (optional, needs 3rd party multidict library) which\n which has more pythonic behaviors than the existing OrderedMultiDict. Experiment\n with getting it returned by the loaders by altering your import statement to\n ``import pvl.new as pvl`` and then using the loaders as usual to get the new object\n returned to you.\n\nChanged\n+++++++\n* Only guaranteed to work with Python 3.6 and above.\n* Rigorously implemented the three dialects of PVL text: PVL itself,\n ODL, and the PDS3 Label Standard. There is a fourth de-facto\n dialect, that of ISIS cube labels that is also handled. Please see\n the \"Standards & Specifications\" section of the documentation.\n* There is now a default dialect for the dump functions: the PDS3 Label Standard.\n This is different and more strict than before, but other output dialects are\n possible. Please see the \"Writing out PVL text\" section in the documentation\n for more information, and how to enable an output similar to the 0.x output.\n* There are now ``pvl.collections`` and ``pvl.exceptions`` modules. There was previously\n an internal ``pvl._collections`` module, and the exception classes were scattered through\n the other modules.\n\nFixed\n+++++\n* All ``datetime.time`` and ``datetime.datetime`` objects returned from the loaders\n are now timezone \"aware.\" Previously some were and some were not.\n* Functionality to correctly parse dash (-) continuation lines in ISIS output is\n now supported.\n* The library now properly parses quoted strings that include backslashes.\n\n\nDeprecated\n++++++++++\n* The `pvl.collections.Units` object is deprecated in favor of\n the new ``pvl.collections.Quantity`` object (really a name-only change, no functionality\n difference).\n\n\n1.0.0-alpha.9 (2020-08-18)\n--------------------------\n* Minor addition to pvl.collections.MutableMappingSequence.\n* Implemented PVLMultiDict which is based on the 3rd Party\n `multidict.MultiDict` object as an option to use instead\n of the default OrderedMultiDict. The new PVLMultiDict\n is better aligned with the Python 3 way that Mapping\n objects behave.\n* Enhanced the existing OrderedMultiDict with some functionality\n that extends its behavior closer to the Python 3 ideal, and\n inserted warnings about how the retained non-Python-3\n behaviors might be removed at the next major patch.\n* Implemented pvl.new that can be included for those that wish\n to try out what getting the new PVLMultiDict returned from\n the loaders might be like by just changing an import statement.\n\n1.0.0-alpha.8 (2020-08-01)\n--------------------------\n* Renamed the _collections module to just collections.\n* Renamed the Units class to Quantity (Units remains, but has a deprecation warning).\n* Defined a new ABC: pvl.collections.MutableMappingSequence\n* More detail for these changes can be found in Issue #62.\n\n1.0.0-alpha.7 (2020-07-29)\n--------------------------\n* Created a new exceptions.py module and grouped all pvl Exceptions\n there. Addresses #58\n* Altered the message that LexerError emits to provide context\n around the character that caused the error.\n* Added bump2version configuration file.\n\n1.0.0-alpha.6 (2020-07-27)\n--------------------------\n* Enforced that all datetime.time and datetime.datetime objects\n returned should be timezone \"aware.\" This breaks 0.x functionality\n where some were and some weren't. Addresses #57.\n\n\n1.0.0-alpha.5 (2020-05-30)\n--------------------------\n* ISIS creates PVL text with unquoted plus signs (\"+\"), needed to adjust\n the ISISGrammar and OmniGrammar objects to parse this properly (#59).\n* In the process of doing so, realized that we have some classes that\n optionally take a grammar and a decoder, and if they aren't given, to default.\n However, a decoder *has* a grammar object, so if a grammar isn't provided, but\n a decoder is, the grammar should be taken from the decoder, otherwise you\n could get confusing behavior.\n* Updated pvl_validate to be explicit about these arguments.\n* Added a --version argument to both pvl_translate and pvl_validate.\n\n1.0.0.-alpha.4 (2020-05-29)\n---------------------------\n* Added the pvl.loadu() function as a convenience function to load PVL text from\n URLs.\n\n1.0.0-alpha.3 (2020-05-28)\n--------------------------\n* Implemented tests in tox and Travis for Python 3.8, and discovered a bug\n that we fixed (#54).\n\n1.0.0-alpha.2 (2020-04-18)\n--------------------------\n* The ability to deal with 3rd-party 'quantity' objects like astropy.units.Quantity\n and pint.Quantity was added and documented, addresses #22.\n\n1.0.0-alpha.1 (2020-04-17)\n--------------------------\nThis is a bugfix on 1.0.0-alpha to properly parse scientific notation\nand deal with properly catching an error.\n\n\n1.0.0-alpha (winter 2019-2020)\n------------------------------\nThis is the alpha version of release 1.0.0 for pvl, and the items\nhere and in other 'alpha' entries may be consolidated when 1.0.0\nis released. This work is categorized as 1.0.0-alpha because\nbackwards-incompatible changes are being introduced to the codebase.\n\n* Refactored code so that it will no longer support Python 2, \n and is only guaranteed to work with Python 3.6 and above.\n* Rigorously implemented the three dialects of PVL text: PVL itself,\n ODL, and the PDS3 Label Standard. There is a fourth de-facto\n dialect, that of ISIS cube labels that is also handled. These\n dialects each have their own grammars, parsers, decoders, and\n encoders, and there are also some 'Omni' versions of same that\n handle the widest possible range of PVL text.\n* When parsing via the loaders, ``pvl`` continues to consume as\n wide a variety of PVL text as is reasonably possible, just like\n always. However, now when encoding via the dumpers, ``pvl`` will\n default to writing out PDS3 Label Standard format PVL text, one\n of the strictest dialects, but other options are available. This\n behavior is different from the pre-1.0 version, which wrote out \n more generic PVL text.\n* Removed the dependency on the ``six`` library that provided Python 2\n compatibility.\n* Removed the dependency on the ``pytz`` library that provided 'timezone'\n support, as that functionality is replaced with the Standard Library's\n ``datetime`` module.\n* The private ``pvl/_numbers.py`` file was removed, as its capability is now\n accomplished with the Python Standard Library.\n* The private ``pvl/_datetimes.py`` file was removed, as its capability is now\n accomplished with the Standard Library's ``datetime`` module.\n* the private ``pvl/_strings.py`` file was removed, as its capabilities are now\n mostly replaced with the new grammar module and some functions in other new\n modules.\n* Internally, the library is now working with string objects, not byte literals, \n so the ``pvl/stream.py`` module is no longer needed.\n* Added an optional dependency on the 3rd party ``dateutil`` library, to parse\n more exotic date and time formats. If this library is not present, the\n ``pvl`` library will gracefully fall back to not parsing more exotic\n formats. \n* Implmented a more formal approach to parsing PVL text: The properties\n of the PVL language are represented by a grammar object. A string is\n broken into tokens by the lexer function. Those tokens are parsed by a\n parser object, and when a token needs to be converted to a Python object,\n a decoder object does that job. When a Python object must be converted to\n PVL text, an encoder object does that job.\n* Since the tests in ``tests/test_decoder.py`` and ``tests/test_encoder.py``\n were really just exercising the loader and dumper functions, those tests were\n moved to ``tests/test_pvl.py``, but all still work (with light modifications for\n the new defaults). Unit tests were added for most of the new classes and\n functions. All docstring tests now also pass doctest testing and are now\n included in the ``make test`` target.\n* Functionality to correctly parse dash (-) continuation lines written by ISIS\n as detailed in #34 is implemented and tested.\n* Functionality to use ``pathlib.Path`` objects for ``pvl.load()`` and\n ``pvl.dump()`` as requested in #20 and #31 is implemented and tested.\n* Functionality to accept already-opened file objects that were opened in \n 'r' mode or 'rb' mode as alluded to in #6 is implemented and tested.\n* The library now properly parses quoted strings that include backslashes\n as detailed in #33.\n* Utility programs pvl_validate and pvl_translate were added.\n* Documentation was updated and expanded.\n\n0.3.0 (2017-06-28)\n------------------\n\n* Create methods to add items to the label\n* Give user option to allow the parser to succeed in parsing broken labels\n\n0.2.0 (2015-08-13)\n------------------\n\n* Drastically increase test coverage.\n* Lots of bug fixes.\n* Add Cube and PDS encoders.\n* Cleanup README.\n* Use pvl specification terminology.\n* Added element access by index and slice.\n\n0.1.1 (2015-06-01)\n------------------\n\n* Fixed issue with reading Pancam PDS Products.\n\n0.1.0 (2015-05-30)\n------------------\n\n* First release on PyPI.\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Python implementation for PVL (Parameter Value Language) parsing and encoding.",
"version": "1.3.2",
"project_urls": {
"Homepage": "https://github.com/planetarypy/pvl"
},
"split_keywords": [
"pvl"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e94fd201cd27b306568013c75b429726267fc9b5049c4b8e23e444cf2eb52f0f",
"md5": "aed1be899229b88666af155c3b08276a",
"sha256": "e25a72f468e82a48b55645d0e96e55c3313f90056832aaeb42b351d1dd648d4e"
},
"downloads": -1,
"filename": "pvl-1.3.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "aed1be899229b88666af155c3b08276a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 66082,
"upload_time": "2022-08-11T23:27:11",
"upload_time_iso_8601": "2022-08-11T23:27:11.980045Z",
"url": "https://files.pythonhosted.org/packages/e9/4f/d201cd27b306568013c75b429726267fc9b5049c4b8e23e444cf2eb52f0f/pvl-1.3.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "512063c4e77d106de29e59fe5d1b123de7c61242300b2315c2a57630022a5bf5",
"md5": "19392a32cf906879501295ca8273cf55",
"sha256": "7d07baa88af26d2ff04a3548a54392de3245dea13f23d964dc8ed725a5efc6a2"
},
"downloads": -1,
"filename": "pvl-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "19392a32cf906879501295ca8273cf55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 153093,
"upload_time": "2022-08-11T23:27:14",
"upload_time_iso_8601": "2022-08-11T23:27:14.036342Z",
"url": "https://files.pythonhosted.org/packages/51/20/63c4e77d106de29e59fe5d1b123de7c61242300b2315c2a57630022a5bf5/pvl-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-11 23:27:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "planetarypy",
"github_project": "pvl",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "pvl"
}
JSON
