Merge pull request #195 from dstansby/doc-fixes

Misc doc fixes

cdflib/cdfread.py

@@ -41,10 +41,6 @@ class CDF:
     >>> x = cdf_file.varget("NameOfVariable", startrec=0, endrec=150)
     """
 
-    version = 3
-    release = 7
-    increment = 0
-
     def __init__(self, path: Union[str, Path], validate: bool = False, string_encoding: str = "ascii", s3_read_method: int = 1):
         """
         Parameters
@@ -248,8 +244,7 @@ def attinq(self, attribute: Union[str, int]) -> ADRInfo:
 
         Returns
         -------
-        dict
-            Dictionary of attribution infromation.
+        ADRInfo
         """
         position = self._first_adr
         if isinstance(attribute, str):
@@ -512,8 +507,7 @@ def globalattsget(self) -> Dict[str, List[Union[str, int]]]:
 
         This function returns all of the global attribute entries,
         in a dictionary (in the form of ``'attribute': {entry: value}``
-        pairs) from a CDF. If there is no entry found, None is
-        returned.
+        pairs) from a CDF.
         """
         byte_loc = self._first_adr
         return_dict: Dict[str, List[Union[str, int]]] = {}
@@ -550,11 +544,6 @@ def varattsget(self, variable: Optional[str] = None) -> Dict[str, Union[None, fl
         this function returns all of the variable attribute entries,
         in a dictionary (in the form of 'attribute': value pair) for
         a variable. If there is no entry found, None is returned.
-        If no variable name is provided, a list of variables are printed.
-
-        Parameters
-        ----------
-        variable :
         """
         if isinstance(variable, int) and self._num_zvariable > 0 and self._num_rvariable > 0:
             raise ValueError("This CDF has both r and z variables. Use variable name")

cdflib/cdfwrite.py

@@ -1,10 +1,3 @@
-"""
-This is a python script to write a CDF file from scratch
-without needing to install the CDF NASA library.
-This Python code only creates V3 CDFs.
-
-@author: Mike Liu
-"""
 import binascii
 import gzip
 import hashlib
@@ -17,14 +10,18 @@
 import struct
 import sys
 import warnings
+from functools import wraps
 from typing import Any, List, Optional, Tuple
 
 import numpy as np
 
 import cdflib.epochs as cdfepoch
 
+__all__ = ["CDF"]
+
 
 def is_open(func):
+    @wraps(func)
     def ensure_open(self, *args, **kwargs):
         if self.is_closed:
             raise OSError("This file is already closed, and can no longer be modified.")

cdflib/dataclasses.py

@@ -4,6 +4,8 @@
 
 import numpy as np
 
+__all__ = ["ADRInfo", "CDFInfo", "CDRInfo", "GDRInfo", "VDRInfo", "AEDR", "VDR", "AEDR", "AttData"]
+
 
 @dataclass
 class ADRInfo:
@@ -23,47 +25,32 @@ class ADRInfo:
 class CDFInfo:
     """
     CDF information.
-
-    Parameters
-    ----------
-    CDF :
-        Path to the CDF.
-    Version :
-        CDF version.
-    Encoding :
-        Endianness of the CDF.
-    Majority :
-        Row/column majority.
-    zVariables :
-        zVariable names.
-    rVariables :
-        rVariable names.
-    Attributes :
-        List of dictionary objects that contain {attribute_name : scope}.
-    Checksum
-        Checksum indicator.
-    Num_rdim :
-        Number of dimensions for rVariables.
-    rDim_sizes :
-        Dimensional sizes for rVariables.
-    Compressed :
-        If CDF is compressed at file level.
-    LeapSecondUpdated :
-        Last updated leap second table.
     """
 
+    #: Path to the CDF.
     CDF: Union[str, Path]
+    #: CDF version.
     Version: str
+    #: Endianness of the CDF.
     Encoding: int
+    #: Row/column majority.
     Majority: str
+    #: zVariable names.
     rVariables: List[str]
+    #: rVariable names.
     zVariables: List[str]
+    #: List of dictionary objects that map attribute_name to scope.
     Attributes: List[Dict[str, str]]
     Copyright: str
+    #: Checksum indicator.
     Checksum: bool
+    #: Number of dimensions for rVariables.
     Num_rdim: int
+    #: Dimensional sizes for rVariables.
     rDim_sizes: List[int]
+    #: If CDF is compressed at file level.
     Compressed: bool
+    #: Last updated leap second table.
     LeapSecondUpdate: Optional[int] = None
 
 
@@ -96,49 +83,34 @@ class GDRInfo:
 class VDRInfo:
     """
     Variable data record info.
-
-    Attributes
-    ----------
-    Variable : str
-        Name of the variable.
-    Num : int
-        Variable number.
-    Var_Type : str
-        Variable type: zVariable or rVariable.
-    Data_Type : str
-        Variable CDF data type.
-    Num_Elements : int
-        Number of elements of the variable.
-    Num_Dims : int
-        Dimensionality of variable record.
-    Dim_sizes :
-        Shape of the variable record.
-    Last_Rec :
-        Maximum written variable number (0-based).
-    Dim_Vary :
-        Dimensional variance(s).
-    Rec_Vary :
-        Record variance.
-    Pad :
-        Padded value (if set).
-    Block_Factor:
-        Blocking factor (if variable is compressed).
     """
 
+    #: Name of the variable.
     Variable: str
+    #: Variable number.
     Num: int
+    #: Variable type: zVariable or rVariable.
     Var_Type: str
+    #: Variable CDF data type.
     Data_Type: int
     Data_Type_Description: str
+    #: Number of elements of the variable.
     Num_Elements: int
+    #: Dimensionality of variable record.
     Num_Dims: int
+    #: Shape of the variable record.
     Dim_Sizes: List[int]
     Sparse: str
+    #: Maximum written variable number (0-based).
     Last_Rec: int
+    #: Record variance.
     Rec_Vary: int
-    Dim_Vary: Union[List[int], List[bool]]
+    #: Dimensional variance(s).
+    Dim_Vary: Union[List[int], List[bool]]  #: a doc
     Compress: int
+    #: Padded value (if set).
     Pad: Optional[int] = None
+    #: Blocking factor (if variable is compressed).
     Block_Factor: Optional[int] = None
 
 
@@ -178,20 +150,13 @@ class VDR:
 class AttData:
     """
     Attribute data.
-
-    Attributes
-    ----------
-    Item_size : int
-        Number of bytes for each entry value.
-    Data_Type : str
-        CDF data type.
-    Num_Items : int
-        Number of values extracted.
-    Data : numpy.ndarray
-        Data as a scalar value, a numpy array or a string.
     """
 
+    #: Number of bytes for each entry value.
     Item_Size: int
+    #: CDF data type.
     Data_Type: str
+    #: Number of values extracted.
     Num_Items: int
+    #: Data as a scalar value, a numpy array or a string.
     Data: np.ndarray

cdflib/epochs.py

@@ -1054,14 +1054,14 @@ def _calc_from_julian(epoch0, epoch1):
 
         Parameters
         ----------
-        epoch0 : int, float, or array-like
+        epoch0 : int, float, array-like
             First element of an epoch array (epoch time in seconds)
-        epoch1 : float or array-like
+        epoch1 : float, array-like
             Second element of an epoch array (epoch time in picoseconds)
 
         Returns
         -------
-        out : array of int
+        out : array-like
             Array of 10 integers (year, month, day, hour, minute, second,
             millisecond, microsecond, nanosecond, picosecond) if a single value
             is input. For array input, the shape is altered by adding another
@@ -1120,15 +1120,15 @@ def breakdown_epoch16(epochs, to_np: bool = False):
 
         Parameters
         ----------
-        epochs : np.complex128 or array-like
+        epochs : array-like
             Single, list, tuple, or np.array of epoch values
         to_np : bool
             Flag for output type, if True will be an np.array, if False
             will be a list (default=False)
 
         Returns
         -------
-        components : list-like of ints
+        components : list
             List or array of date and time values.  The last axis contains
             (in order): year, month, day, hour, minute, second, millisecond,
             microsecond, nanosecond, and picosecond
@@ -1491,7 +1491,7 @@ def breakdown_epoch(epochs, to_np: bool = False):
 
         Returns
         -------
-        components : list-like of ints
+        components : list
             List or array of date and time values.  The last axis contains
             (in order): year, month, day, hour, minute, second, and millisecond
 

doc/changelog.rst

@@ -12,9 +12,28 @@ for older versions of Python, but this is not guarenteed. If you need to
 use ``cdflib`` on an older version of Python, please open an issue to
 discuss whether the ``cdflib`` maintainers can support this.
 
-Breaking changes
-----------------
-- The CDF factory class (``cdflib.CDF``) has been removed, and `cdflib.CDF`
+Changes to CDF method returns
+-----------------------------
+Most of the methods that return data from the CDF reader class have had their
+return types changed from dictionaries to dataclasses. This allows the return
+type to be more clearly documented (see :ref:`dataclasses`), for internal
+checks to be made to make sure data types are consistent, and a nicer
+representation when the return values are printed.
+
+Where previously an item would have been accessed as ``dict["value"]``,
+items in the dataclasses can be accessed using ``dataclass.value``.
+
+The methods that have been updated are:
+
+- `cdflib.cdfread.CDF.vdr_info`
+- `cdflib.cdfread.CDF.attinq`
+- `cdflib.cdfread.CDF.attget`
+- `cdflib.cdfread.CDF.varget`
+- `cdflib.cdfread.CDF.varinq`
+
+Other breaking changes
+----------------------
+- The CDF factory class (``cdflib.CDF``) has been removed, and ``cdflib.CDF``
   is now the reader class. This change has been made to prevent potential
   confusion when the user makes a mistake in specifying the file to open,
   and ``cdflib`` would silently create a writer class instead. If you want
@@ -31,16 +50,12 @@ Breaking changes
   code now behaves as if ``to_np=True`` throughout.
   This change has been made to reduce code omplexity and make maintaining
   the code easier.
-- The ``expand`` keyword argument to ``CDF.varget`` has been removed.
+- The ``expand`` keyword argument to `cdflib.cdfread.CDF.varget` has been removed.
   Use ``CDF.varinq`` to get variable information instead.
 - The ``expand`` keyword argument to ``CDF.globalattsget`` and ``CDF.varattsget`` has been removed.
-  Use ``CDF.attinq`` to get attribute information instead.
-- ``CDF.vdr_info`` now returns a dataclass instead of a dict.
-- ``CDF.attinq`` now returns a dataclass instead of a dict.
-- ``CDF.attget`` now returns a dataclass instead of a dict.
-- ``CDF.varget`` now returns a dataclass instead of a dict.
-- ``CDF.varinq`` now returns a dataclass instead of a dict.
+  Use `cdflib.cdfread.CDF.attinq` to get attribute information instead.
 - Removed ``CDF.print_attrs``
+- The ``version``, ``release``, and ``increement`` attributes of ``CDF`` have been removed.
 
 Bugfixes
 --------

doc/conf.py

@@ -41,15 +41,19 @@
     "sphinx.ext.autosummary",
     "sphinx_copybutton",
     "sphinx.ext.linkcode",
+    "sphinx.ext.intersphinx",
     "sphinx_automodapi.automodapi",
 ]
 
 numpydoc_class_members_toctree = False
 numpydoc_show_class_members = False
+autodoc_typehints = "description"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
+default_role = "any"
+nitpicky = True
+nitpick_ignore = [("py:class", "array-like"), ("py:class", "optional")]
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -142,8 +146,12 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/3": None}
-# autodoc_mock_imports = ['xarray', 'astropy']
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "astropy": ("https://docs.astropy.org/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+}
 
 
 def linkcode_resolve(domain, info):

doc/modules/cdfread.rst

@@ -1,6 +1,13 @@
 CDF Reader Class
 ================
 
+.. autoclass:: cdflib.cdfread.CDF
+   :members:
+   :undoc-members:
+
+Sample Usage
+------------
+
 To begin accessing the data within a CDF file, first create a new CDF class.
 This can be done with the following commands
 
@@ -13,8 +20,4 @@ For example:
 
 >>> x = cdf_file.varget("NameOfVariable", startrec = 0, endrec = 150)
 
-This command will return all data inside of the variable `Variable1`, from records 0 to 150.
-
-.. automodule:: cdflib
-   :undoc-members:
-   :show-inheritance:
+This command will return all data inside of the variable ``Variable1``, from records 0 to 150.

doc/modules/cdfwrite.rst

@@ -1,8 +1,8 @@
 CDF Writer Class
 =================
 
-.. automodapi:: cdflib.cdfwrite
-    :no-inheritance-diagram:
+.. autoclass:: cdflib.cdfwrite.CDF
+   :members:
 
 
 Sample Usage