Merge pull request #14 from davidhassell/CF-1.8

Changes for CF-1.8

Changelog.rst

@@ -1,3 +1,31 @@
+version 1.8.0
+--------------
+----
+
+**2020-??-??**
+
+* First release for CF-1.8 (does not include netCDF hierarchical
+  groups functionality).
+* Implementation of simple geometries for CF-1.8
+  (https://github.com/NCAS-CMS/cfdm/issues/11).
+* Implementing of string data-types for CF-1.8
+  (https://github.com/NCAS-CMS/cfdm/issues/12).
+* New function: `cfdm.example_field`
+  (https://github.com/NCAS-CMS/cfdm/issues/18)
+* New attributes: `cfdm.Field.dtype`, `cfdm.Field.ndim`,
+  `cfdm.Field.shape`, `cfdm.Field.size`
+* New method: `cfdm.Data.any`
+* New ``paths`` keyword parameter to `cfdm.environment`
+* Changed minimum netCDF4 dependency to version 1.5.3.
+* Changed minimum cftime dependency to version 1.1.1.
+* Fixed bug that prevented the writing of ``'NETCDF3_64BIT_OFFSET'``
+  and ``'NETCDF3_64BIT_DATA'`` format files
+  (https://github.com/NCAS-CMS/cfdm/issues/9).
+* Fixed bug that caused a failure when a "_FillValue" or
+  "missing_value" property is set and data type conversions are
+  specified with the ``datatype`` keyword to `cfdm.write`
+  (https://github.com/NCAS-CMS/cfdm/issues/16).
+
 version 1.7.11
 --------------
 ----
@@ -6,7 +34,7 @@ version 1.7.11
 
 * New methods: `cfdm.Field.compress`, `cfdm.Field.uncompress`
 * New methods: `cfdm.Data.flatten`, `cfdm.Data.uncompress`
-* New keyword parameters to `cfdm.Data`: ``dtype``, ``mask``.
+* New  ``dtype`` and ``mask`` keyword parameters to `cfdm.Data`
 * Changed the default value of the ``ignore_compression`` parameter to
   `True`.
 
@@ -29,7 +57,7 @@ version 1.7.9
 **2019-11-07**
 
 * Fixed bug relating to setting of parameters on datum and coordinate
-  conversion objects of coordinate conversion constucts
+  conversion objects of coordinate conversion constructs
   (https://github.com/NCAS-CMS/cfdm/issues/6).
 
 version 1.7.8
@@ -65,8 +93,8 @@ version 1.7.6
 **2019-06-05**
 
 * Added attributes `_ATOL` and `_RTOL` to facilitate subclassing.
-* Fixed bug in `Field.convert`.
-* Fixed bug in `core.constructs.new_identifier`.
+* Fixed bug in `cfdm.Field.convert`.
+* Fixed bug in `cfdm.core.constructs.new_identifier`.
 
 version 1.7.5
 -------------
@@ -84,70 +112,76 @@ version 1.7.4
 
 **2019-05-14**
 
-* Changed behaviour of `Constructs.filter_by_axis`.
-* New methods: `Data.has_units`, `Data.has_calendar`, `Data.has_fill_value`.
-* New keyword 'constructs' to `Field.transpose`.
-* Keyword 'axes' to Field.set_data is now optional.
+* Changed behaviour of `cfdm.Constructs.filter_by_axis`.
+* New methods: `cfdm.Data.has_units`, `cfdm.Data.has_calendar`,
+  `cfdm.Data.has_fill_value`.
+* New ``constructs`` keyword parameter to `Field.transpose`.
+* Keyword parameter ``axes`` to `cfdm.Field.set_data` is now optional.
 * Added the 'has_bounds' method to constructs that have data but can't
   have bounds.
-* New methods: `DomainAxis.nc_is_unlimited`,
-  `DomainAxis.nc_set_unlimited`.
+* New methods: `cfdm.DomainAxis.nc_is_unlimited`,
+  `cfdm.DomainAxis.nc_set_unlimited`.
 * Made Data a virtual subclass of Array.   
-* Deprecated methods: `Field.nc_unlimited`, `Field.nc_clear_unlimited`,
-  `Field.nc_clear_unlimited`.
+* Deprecated methods: `cfdm.Field.nc_unlimited`,
+  `cfdm.Field.nc_clear_unlimited`, `cfdm.Field.nc_clear_unlimited`.
 * Fixed bug when writing new horizontal coordinate reference for the
   vertical datum.
 * Fixed bug in `del_data` methods.
 * Fixed bug with in-place operations.
 * Fixed bug with position in some `insert_dimension` methods.
 * Fixed bug that sometimes made duplicate netCDF dimensions when
   writing to a file.
-* Added _shape keyword to `Field.set_data_axes` to allow the data shape
-  to be checked prior to insertion.
+* Added _shape keyword to `cfdm.Field.set_data_axes` to allow the data
+  shape to be checked prior to insertion.
 * Added the '_custom' attribute to facilitate subclassing.
-* New class `mixin.NetCDFUnlimitedDimension` replaces
-  `mixin.NetCDFUnlimitedDimensions`, which is deprecated.
-* New method `CFDMImplementation.nc_is_unlimited_axis` replaces
-  `CFDMImplementation.nc_get_unlimited_axes`, which is deprecated.
-* New method `CFDMImplementation.nc_set_unlimited_axis` replaces
-  `CFDMImplementation.nc_set_unlimited_dimensions`, which is deprecated.
+* New class `cfdm.mixin.NetCDFUnlimitedDimension` replaces
+  `cfdm.mixin.NetCDFUnlimitedDimensions`, which is deprecated.
+* New method `cfdm.CFDMImplementation.nc_is_unlimited_axis` replaces
+  `cfdm.CFDMImplementation.nc_get_unlimited_axes`, which is
+  deprecated.
+* New method `cfdm.CFDMImplementation.nc_set_unlimited_axis` replaces
+  `cfdm.CFDMImplementation.nc_set_unlimited_dimensions`, which is
+  deprecated.
 
 version 1.7.3
 -------------
 ----
 
 **2019-04-24**
 
-* New method: `Constructs.filter_by_size`.
-* New method: `Data.uncompress`.
-* Changed the default behaviours of the `Construct.filter_by_axis`,
-  `Construct.filter_by_size`, `Construct.filter_by_naxes`,
-  `Construct.filter_by_property`, `Construct.filter_by_ncvar`,
-  `Construct.filter_by_ncdim`, `Construct.filter_by_method`,
-  `Construct.filter_by_measure` methods in the case when no arguments
-  are provided: Now returns all possible constructs that *could* have
-  the feature, with any values.
+* New method: `cfdm.Constructs.filter_by_size`.
+* New method: `cfdm.Data.uncompress`.
+* Changed the default behaviours of the
+  `cfdm.Construct.filter_by_axis`, `cfdm.Construct.filter_by_size`,
+  `cfdm.Construct.filter_by_naxes`,
+  `cfdm.Construct.filter_by_property`,
+  `cfdm.Construct.filter_by_ncvar`, `cfdm.Construct.filter_by_ncdim`,
+  `cfdm.Construct.filter_by_method`,
+  `cfdm.Construct.filter_by_measure` methods in the case when no
+  arguments are provided: Now returns all possible constructs that
+  *could* have the feature, with any values.
 * Renamed the "underlying_array" methods to "source"
 * Added _field_data_axes attribute to `Constructs` instances.
 * Added _units and _fill_value arguments to get_data method.
 * Moved contents of cfdm/read_write/constants.py to `NetCDFRead` and
   `NetCDFWrite`.
-* Fixed bug in `CoordinateReference.clear_coordinates`.
-* Fixed bug in `Field.convert` (which omitted domain ancillaries in
-  the result).
-* Added **kwargs parameter to `CFDMImplementation.initialise_Data`, to
-  facilitate subclassing.
-* Added `NetCDFRead._customize_read_vars` to facilitate sublcassing.
-* Added `NetCDFWrite._transform_strings` to facilitate sublcassing.
+* Fixed bug in `cfdm.CoordinateReference.clear_coordinates`.
+* Fixed bug in `cfdm.Field.convert` (which omitted domain ancillaries
+  in the result).
+* Added **kwargs parameter to
+  `cfdm.CFDMImplementation.initialise_Data`, to facilitate
+  subclassing.
+* Added `NetCDFRead._customize_read_vars` to facilitate subclassing.
+* Added `NetCDFWrite._transform_strings` to facilitate subclassing.
 
 version 1.7.2
 -------------
 ----
 
 **2019-04-05**
 
-* New "mode" parameter options to `Constructs.filter_by_axis`: 'exact',
-  'subset', 'superset'.
+* New ``mode`` parameter options to `cfdm.Constructs.filter_by_axis`:
+  ``'exact'``, ``'subset'``, ``'superset'``.
 * Enabled setting of HDF5 chunksizes.
 * Fixed bug that caused coordinate bounds to be not sliced during
   subspacing (https://github.com/NCAS-CMS/cfdm/issues/1).
@@ -158,10 +192,10 @@ version 1.7.1
 
 **2019-04-02**
 
-* New methods `Constructs.clear_filters_applied`,
-  `Constructs.filter_by_naxes`.
-* Changed behaviour of `Constructs.unfilter` and
-  `Constructs.inverse_filters`: added depth keyword and changed
+* New methods `cfdm.Constructs.clear_filters_applied`,
+  `cfdm.Constructs.filter_by_naxes`.
+* Changed behaviour of `cfdm.Constructs.unfilter` and
+  `cfdm.Constructs.inverse_filters`: added depth keyword and changed
   default.
 
 version 1.7.0

README.md

@@ -1,18 +1,56 @@
 cfdm
 ====
 
-**cfdm** is a complete implementation of the [CF data
-model](https://www.geosci-model-dev.net/10/4619/2017), that identifies
-the fundamental elements of the [CF
-conventions](http://cfconventions.org/) and shows how they relate to
-each other, independently of the
-[netCDF](https://www.unidata.ucar.edu/software/netcdf/) encoding.
+A complete implementation of the CF data model.
+
+Documentation
+=============
+
+https://ncas-cms.github.io/cfdm
+
+Tutorial
+========
+
+https://ncas-cms.github.io/cfdm/tutorial
+
+Installation
+============
+
+https://ncas-cms.github.io/cfdm/installation
+
+Functionality
+=============
+
+The ``cfdm`` package implements the CF data model
+(https://doi.org/10.5194/gmd-10-4619-2017) for its internal data
+structures and so is able to process any CF-compliant dataset. It is
+not strict about CF-compliance, however, so that partially conformant
+datasets may be ingested from existing datasets and written to new
+datasets. This is so that datasets which are partially conformant may
+nonetheless be modified in memory.
 
 The central element defined by the CF data model is the **field
 construct**, which corresponds to a CF-netCDF data variable with all
 of its metadata.
 
-The **cfdm** package can
+A simple example of reading a field construct from a file and
+inspecting it:
+
+    >>> import cfdm
+    >>> f = cfdm.read('file.nc')
+    >>> f
+    [<Field: air_temperature(time(12), latitude(64), longitude(128)) K>]
+    >>> print(f[0])
+    Field: air_temperature (ncvar%tas)
+    ----------------------------------
+    Data            : air_temperature(time(12), latitude(64), longitude(128)) K
+    Cell methods    : time(12): mean (interval: 1.0 month)
+    Dimension coords: time(12) = [0450-11-16 00:00:00, ..., 0451-10-16 12:00:00] noleap
+                    : latitude(64) = [-87.8638, ..., 87.8638] degrees_north
+                    : longitude(128) = [0.0, ..., 357.1875] degrees_east
+                    : height(1) = [2.0] m
+
+The ``cfdm`` package can:
 
 * read field constructs from netCDF datasets,
 * create new field constructs in memory,
@@ -21,25 +59,11 @@ The **cfdm** package can
 * modify field construct metadata and data,
 * create subspaces of field constructs,
 * write field constructs to netCDF datasets on disk,
-* incorporate, and create, metadata stored in external files, and
+* incorporate, and create, metadata stored in external files,
 * read, write, and create data that have been compressed by convention
   (i.e. ragged or gathered arrays), whilst presenting a view of the
-  data in its uncompressed form.
-
-Documentation
-=============
-
-https://ncas-cms.github.io/cfdm
-
-Tutorial
-========
-
-https://ncas-cms.github.io/cfdm/tutorial
-
-Installation
-============
-
-https://ncas-cms.github.io/cfdm/installation.html
+  data in its uncompressed form, and
+* read, write, and create coordinates defined by geometry cells.
 
 Command line utility
 ====================
@@ -53,4 +77,4 @@ Tests
 
 Tests are run from within the ``cfdm/test`` directory:
 
-    python run_tests.py
+    $ python run_tests.py

README.release

@@ -1,29 +1,41 @@
-* Change the version and date in cfdm/core/__init__.py (__version__ and
-  __date__ variables)
+* Change the version and date in cfdm/core/__init__.py (__version__
+  and __date__ variables)
 
-* If required, change the CF conventions version in cfdm/core/__init__.py
-  (__cf_version__ variable)
+* If required, change the CF conventions version in
+  cfdm/core/__init__.py (__cf_version__ variable)
 
 * Make sure that README.md is up to date.
 
 * Make sure that Changelog.rst is up to date.
 
+* Make sure that any new attributes, methods and keyword arguments (as
+  listed in the change log) have on-line documentation. This may
+  require additions to the .rst files in docs/source/class/
+
 * Create a link to the new documentation in docs/source/releases.rst
 
 * Create a source tarball using `python setup.py sdist`
 
-* Test the tarball release using `test_release <vn>`
-  (e.g. ./test_release 1.7.12). Do this for python2.7 and python3.
+* Test the tarball release using `./test_release <vn>`
+  (e.g. ./test_release 1.8.0). Do this for python2.7 and python3.
+
+* Test tutorial code:
+
+cd docs/source
+./extract_tutorial_code
+./reset_test_tutorial
+cd test_tutorial
+python ../tutorial.py
 
-* Update the latest documentation using `./release_latest_docs <vn>`
-  (e.g. ./release_latest_docs 1.7.12)
+* Update the latest documentation using `./release_docs <vn> latest`
+  (e.g. ./release_docs 1.8.0 latest)
 
 * Create an archived copy of the documentation using
-  `./release_archive_docs <vn>` (e.g. ./release_archive_docs 1.7.12)
+  `./release_docs <vn> archive` (e.g. ./release_docs 1.8.0 archive)
 
 * Push recent commits using `git push origin master`
 
-* Tag the release using `./tag <vn>` (e.g. ./tag 1.7.11)
+* Tag the release using `./tag <vn>` (e.g. ./tag 1.8.0)
 
 * Upload the source tarball to PyPi