Merge pull request #12 from insightindustry/develop

PR for v.0.2.0
insightindustry · Jan 5, 2023 · 4243118 · 4243118
2 parents 6b6e776 + 0204776
commit 4243118
Show file tree

Hide file tree

Showing 10 changed files with 210 additions and 65 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,5 +1,26 @@
 ------------------
 
+Release 0.2.0
+=========================================
+
+.. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.2.0
+   :target: https://travis-ci.com/insightindustry/spss-converter
+   :alt: Build Status (Travis CI)
+
+.. image:: https://codecov.io/gh/insightindustry/spss-converter/branch/v.0.2.0/graph/badge.svg
+   :target: https://codecov.io/gh/insightindustry/spss-converter
+   :alt: Code Coverage Status (Codecov)
+
+.. image:: https://readthedocs.org/projects/spss-converter/badge/?version=v.0.2.0
+   :target: http://spss-converter.readthedocs.io/en/latest/?badge=v.0.2.0
+   :alt: Documentation Status (ReadTheDocs)
+
+* Added explicit support for the ``layout`` keyword argument in
+  ``write.from_json()`` and ``write.from_yaml()`` (#11).
+* Loosened version requirements for Pandas and Pyreadstat.
+
+------------------
+
 Release 0.1.2
 =========================================
 

diff --git a/README.rst b/README.rst
@@ -24,6 +24,20 @@ SPSS Converter
           :target: http://spss-converter.readthedocs.io/en/latest/?badge=latest
           :alt: Documentation Status (ReadTheDocs)
 
+   * - `v.0.2 <https://github.com/insightindustry/spss-converter/tree/v.0.2.0>`_
+     -
+       .. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.2.0
+          :target: https://travis-ci.com/insightindustry/spss-converter
+          :alt: Build Status (Travis CI)
+
+       .. image:: https://codecov.io/gh/insightindustry/spss-converter/branch/v.0.2.0/graph/badge.svg
+          :target: https://codecov.io/gh/insightindustry/spss-converter
+          :alt: Code Coverage Status (Codecov)
+
+       .. image:: https://readthedocs.org/projects/spss-converter/badge/?version=v.0.2.0
+          :target: http://spss-converter.readthedocs.io/en/latest/?badge=v.0.2.0
+          :alt: Documentation Status (ReadTheDocs)
+
    * - `v.0.1 <https://github.com/insightindustry/spss-converter/tree/v.0.1.0>`_
      -
        .. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.1.0

diff --git a/docs/_dependencies.rst b/docs/_dependencies.rst
@@ -2,7 +2,7 @@
    :header-rows: 1
 
    * - Python 3.x
-   * - | * `Pandas v0.24 <https://pandas.pydata.org/docs/>`_ or higher
+   * - | * `Pandas v1.2 <https://pandas.pydata.org/docs/>`_ or higher
        | * `Pyreadstat v1.0 <https://github.com/Roche/pyreadstat>`_ or higher
        | * `OpenPyXL v.3.0.7 <https://openpyxl.readthedocs.io/en/stable/>`_ or higher
        | * `PyYAML v3.10 <https://github.com/yaml/pyyaml>`_ or higher

diff --git a/docs/_unit_tests_code_coverage.rst b/docs/_unit_tests_code_coverage.rst
@@ -18,16 +18,30 @@
          :target: http://spss-converter.readthedocs.io/en/latest/?badge=latest
          :alt: Documentation Status (ReadTheDocs)
 
-* - `v.0.1 <https://github.com/insightindustry/spss-converter/tree/v.0.1.2>`_
-  -
-    .. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.1.2
-      :target: https://travis-ci.com/insightindustry/spss-converter
-      :alt: Build Status (Travis CI)
-
-    .. image:: https://codecov.io/gh/insightindustry/spss-converter/branch/v.0.1.2/graph/badge.svg
-      :target: https://codecov.io/gh/insightindustry/spss-converter
-      :alt: Code Coverage Status (Codecov)
-
-    .. image:: https://readthedocs.org/projects/spss-converter/badge/?version=v.0.1.2
-      :target: http://spss-converter.readthedocs.io/en/latest/?badge=v.0.1.2
-      :alt: Documentation Status (ReadTheDocs)
+   * - `v.0.2 <https://github.com/insightindustry/spss-converter/tree/v.0.2.0>`_
+     -
+       .. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.2.0
+         :target: https://travis-ci.com/insightindustry/spss-converter
+         :alt: Build Status (Travis CI)
+
+       .. image:: https://codecov.io/gh/insightindustry/spss-converter/branch/v.0.2.0/graph/badge.svg
+         :target: https://codecov.io/gh/insightindustry/spss-converter
+         :alt: Code Coverage Status (Codecov)
+
+       .. image:: https://readthedocs.org/projects/spss-converter/badge/?version=v.0.2.0
+         :target: http://spss-converter.readthedocs.io/en/latest/?badge=v.0.2.0
+         :alt: Documentation Status (ReadTheDocs)
+
+   * - `v.0.1 <https://github.com/insightindustry/spss-converter/tree/v.0.1.2>`_
+     -
+       .. image:: https://travis-ci.com/insightindustry/spss-converter.svg?branch=v.0.1.2
+         :target: https://travis-ci.com/insightindustry/spss-converter
+         :alt: Build Status (Travis CI)
+
+       .. image:: https://codecov.io/gh/insightindustry/spss-converter/branch/v.0.1.2/graph/badge.svg
+         :target: https://codecov.io/gh/insightindustry/spss-converter
+         :alt: Code Coverage Status (Codecov)
+
+       .. image:: https://readthedocs.org/projects/spss-converter/badge/?version=v.0.1.2
+         :target: http://spss-converter.readthedocs.io/en/latest/?badge=v.0.1.2
+         :alt: Documentation Status (ReadTheDocs)
diff --git a/requirements.dev.txt b/requirements.dev.txt
@@ -1,5 +1,5 @@
-pandas==1.2.0
-pyreadstat==1.0.6
+pandas>=1.2.0
+pyreadstat>=1.0.6
 PyYAML==5.3.1
 simplejson==3.17.2
 validator-collection>=1.5.0

diff --git a/requirements.txt b/requirements.txt
@@ -1,5 +1,5 @@
-pandas==1.2.0
-pyreadstat==1.0.6
+pandas>=1.2.0
+pyreadstat>=1.0.6
 PyYAML==5.3.1
 simplejson==3.17.2
 validator-collection>=1.5.0

diff --git a/spss_converter/__version__.py b/spss_converter/__version__.py
@@ -1,2 +1,2 @@
 # -*- coding: utf-8 -*-
-__version__ = '0.1.2'
+__version__ = '0.2.0'
diff --git a/spss_converter/write.py b/spss_converter/write.py
@@ -221,6 +221,7 @@ def from_dict(as_dict: dict,
 
 def from_json(as_json: Union[str, 'PathLike[Any]', BytesIO],
               target: Optional[Union['PathLike[Any]', BytesIO]] = None,
+              layout: str = 'records',
               compress: bool = False,
               **kwargs):
     """Convert JSON data into an SPSS dataset.
@@ -242,12 +243,33 @@ def from_json(as_json: Union[str, 'PathLike[Any]', BytesIO],
     :type target: Path-like / :class:`BytesIO <python:io.BytesIO>` /
       :obj:`None <python:None>`
 
+    :param layout: Indicates the layout schema to use for the JSON representation of the
+      data. Accepts:
+
+        * ``records``, where the resulting JSON object represents an array of objects
+          where each object corresponds to a single record, with key/value pairs for each
+          column and that record's corresponding value
+        * ``table``, where the resulting JSON object contains a metadata (data map)
+          describing the data schema along with the resulting collection of record objects
+
+      Defaults to ``records``.
+
+    :type layout: :class:`str <python:str>`
+
     :param compress: If ``True``, will return data in the compressed ZSAV format. If
       ``False``, will return data in the standards SAV format. Defaults to ``False``.
     :type compress: :class:`bool <python:bool>`
 
     :param kwargs: Additional keyword arguments which will be passed onto the
       :func:`pandas.read_json() <pandas:pandas.read_json>` function.
+
+      .. warning::
+
+        If you supply an ``orient`` keyword argument (which is supported by
+        :func:`pandas.read_json() <pandas:pandas.read_json>`), the ``orient``
+        value will *override* the value supplied for ``layout``. This is an
+        advanced use case, so use with caution.
+
     :type kwargs: :class:`dict <python:dict>`
 
     :returns: A :class:`BytesIO <python:io.BytesIO>` object containing the SPSS data if
@@ -256,7 +278,16 @@ def from_json(as_json: Union[str, 'PathLike[Any]', BytesIO],
     :rtype: :class:`BytesIO <python:io.BytesIO>` or :obj:`None <python:None>`
 
     """
-    df = pandas.read_json(as_json, **kwargs)
+    if layout not in ['records', 'table']:
+        raise errors.InvalidLayoutError('layout must be either "records" or "table". '
+                                        f'Was: "{layout}"')
+
+    orient = kwargs.pop('orient', layout)
+
+    df = pandas.read_json(as_json,
+                          orient = orient,
+                          **kwargs)
+
     result = from_dataframe(df,
                             target = target,
                             compress = compress)
@@ -266,6 +297,7 @@ def from_json(as_json: Union[str, 'PathLike[Any]', BytesIO],
 
 def from_yaml(as_yaml: Union[str, 'PathLike[Any]', BytesIO],
               target: Optional[Union['PathLike[Any]', BytesIO]] = None,
+              layout: str = 'records',
               compress: bool = False,
               **kwargs):
     """Convert YAML data into an SPSS dataset.
@@ -287,12 +319,35 @@ def from_yaml(as_yaml: Union[str, 'PathLike[Any]', BytesIO],
     :type target: Path-like / :class:`BytesIO <python:io.BytesIO>` /
       :obj:`None <python:None>`
 
+    :param layout: Indicates the layout schema to expect for the YAML representation of the
+      data. Accepts:
+
+        * ``records``, where the resulting JSON object represents an array of objects
+          where each object corresponds to a single record, with key/value pairs for each
+          column and that record's corresponding value
+        * ``table``, where the resulting JSON object contains a metadata (data map)
+          describing the data schema along with the resulting collection of record objects
+
+      Defaults to ``records``.
+    :type layout: :class:`str <python:str>`
+
     :param compress: If ``True``, will return data in the compressed ZSAV format. If
       ``False``, will return data in the standards SAV format. Defaults to ``False``.
     :type compress: :class:`bool <python:bool>`
 
     :param kwargs: Additional keyword arguments which will be passed onto the
-      :meth:`DataFrame.from_dict() <pandas:pandas.DataFrame.from_dict>` method.
+      :meth:`pandas.from_json() <pandas:pandas.from_json>` function.
+
+    :param kwargs: Additional keyword arguments which will be passed onto the
+      :func:`pandas.read_json() <pandas:pandas.read_json>` function.
+
+      .. warning::
+
+        If you supply an ``orient`` keyword argument (which is supported by
+        :func:`pandas.read_json() <pandas:pandas.read_json>`), the ``orient``
+        value will *override* the value supplied for ``layout``. This is an
+        advanced use case, so use with caution.
+
     :type kwargs: :class:`dict <python:dict>`
 
     :returns: A :class:`BytesIO <python:io.BytesIO>` object containing the SPSS data if
@@ -312,6 +367,7 @@ def from_yaml(as_yaml: Union[str, 'PathLike[Any]', BytesIO],
 
     return from_json(as_json,
                      target = target,
+                     layout = layout,
                      compress = compress,
                      **kwargs)