Metadata-Version: 1.1
Name: BespON
Version: 0.3.0
Summary: Python library for BespON
Home-page: http://github.com/gpoore/bespon_py
Author: Geoffrey M. Poore
Author-email: gpoore@gmail.com
License: BSD
Description: =====================================
            ``bespon`` package for Python
        =====================================
        
        
        
        The ``bespon`` package for Python encodes and decodes data in the
        `BespON <https://bespon.org>`_ format.
        
        
        
        Basic usage
        ===========
        
        Data is loaded in a manner analogous to Python's ``json`` module:
        
        * ``bespon.load(<file-like object>)``
        * ``bespon.loads(<string or bytes>)``
        
        Similarly, dumping data to a file or string:
        
        * ``bespon.dump(<obj>, <file-like object>)``
        * ``bespon.dumps(<obj>)``
        
        At the moment, only dumping in indentation-style syntax is possible.  Support
        for other styles is under development.  Only dicts, lists, Unicode
        strings, byte strings, floats, ints, bools, and ``None`` are currently
        supported for dumping.  Loading supports additional data types.
        
        
        
        Lossless round-trip support
        ===========================
        
        There is also support for lossless round-tripping.  Data can be loaded,
        values can be modified, and then data can be saved again with minimal
        impact on the data file layout.
        
        Data can be loaded from a file or string into an instance of the
        ``RoundtripAst`` class.
        
        * ``bespon.load_roundtrip_ast(<file-like object>)``
        * ``bespon.loads_roundtrip_ast(<string or bytes>)``
        
        This class has two methods that allow data to be modified.
        
        * ``replace_val(<path>, <obj>)`` This replaces the object currently located
          at ``<path>`` within the data with ``<obj>``.  ``<path>`` must be a list
          or tuple consisting of dict keys and list indices.  ``<obj>`` must currently be a Unicode string, float, int, or bool, and must have the same
          type as the object it is replacing.
        * ``replace_key(<path>, <obj>)`` This replaces the dict key at the end of
          ``<path>`` with the new key ``<obj>`` (which will map to the same value as
          the replaced key).  ``<obj>`` must be a Unicode string, int, or bool,
          and must have the same type as the object it is replacing.
        
        After data in a ``RoundtripAst`` instance has been modified, it may be encoded
        back into a string with the ``dumps()`` method.  An example is shown below.
        
        ::
        
            >>> ast = bespon.loads_roundtrip_ast("""
            key.subkey.first = 123   # Comment
            key.subkey.second = 0b1101
            key.subkey.third = `literal \string`
            """)
            >>> ast.replace_key(['key', 'subkey'], 'sk')
            >>> ast.replace_val(['key', 'sk', 'second'], 7)
            >>> ast.replace_val(['key', 'sk', 'third'], '\\another \\literal')
            >>> ast.replace_key(['key', 'sk', 'third'], 'fourth')
            >>> print(ast.dumps())
        
            key.sk.first = 123   # Comment
            key.sk.second = 0b111
            key.sk.fourth = `\another \literal`
        
        This example illustrates several of BespON's round-trip capabilities.
        
        * Comments and layout are preserved exactly.
        * Key renaming works with key paths.  Every time a key appears in key paths,
          it is renamed.
        * When a number is modified, the new value is expressed in the same base as
          the old value.
        * When a quoted string is modified, the new value is quoted in the same
          style as the old value (at least to the extent that this is practical).
        * As soon as a key is modified, the new key must be used for further
          modifications.  The old key is invalid.
        
        Currently, round-trip support is limited to changing the value of any Unicode
        string, float, int, or bool, without changing the type.  Support for changing
        data types and for more general data manipulation will be added in the future.
        
        
        
        Advanced loading and dumping
        ============================
        
        The loading and dumping functions support several keyword arguments to
        customize data handling.
        
        **Loading**
        
        * ``aliases`` (boolean, default ``True``):  Allow aliases.
        * ``circular_references`` (boolean, default ``False``):  Allow aliases to
          create circular references.
        * ``custom_parsers`` (dict, default ``None``):  Replace the default parser
          for a specified type with a custom parser.  For example, using
          ``custom_parsers={'int': float}`` would cause all integers to be parsed
          with the ``float()`` function.
        * ``extended_types`` (boolean, default ``False``):  Enable preliminary support
          for ``set`` and ``odict`` tagged collections (for example, ``(set)> [1, 2,
          3]``).  Enable preliminary support for complex number literals and rational
          number literals.  Complex numbers currently use the general form
          ``1.0+2.0i``, where the real part is optional, the imaginary unit is
          represented with ``i``, and numbers must be floats (either in decimal or hex
          form).  Rational numbers use the form ``1/2``, where the numerator and
          denominator must both be decimal integers, and any sign must come before the
          fraction.
        * ``float_overflow_to_inf`` (boolean, default ``False``):  Whether
          non-``inf`` floats are permitted to overflow into ``inf`` without raising an
          error.
        * ``integers`` (boolean, default ``True``):  Whether integers are permitted.
          Otherwise they are interpreted as floats.
        * ``only_ascii_unquoted`` (boolean, default ``True``):  Whether non-ASCII
          identifier-style strings are allowed unquoted.
        * ``only_ascii_source`` (boolean, default ``False``):  Whether non-ASCII code
          points are allowed to appear literally in the source (without being
          represented via backslash-escapes).
        * ``python_types`` (boolean, default ``False``):  Enable preliminary support
          for Python-specific data types.  Currently this only supports ``tuple``.
        * ``max_nesting_depth`` (int, default ``100``):  Maximum permitted nesting
          depth for collections.
        
        **Dumping**
        
        * ``hex_floats`` (boolean, default ``False``):  Whether floats are
          dumped in hex form.
        * ``max_nesting_depth`` (int, default ``100``):  Maximum permitted nesting
          depth of collections.
        
        
        
        Spec conformance
        ================
        
        The ``bespon`` package passes the
        `BespON test suite <https://github.com/bespon/bespon_tests>`_.
        
Keywords: configuration,serialization,interchange
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Utilities
