History and Deprecations

Revision History

Important changes of note with each release:

2.6.0

  • Add util.add_metadata_from_dict function to allow adding metadata direct from a python dictionary.

  • Add file_format optional argument to util.add_metadata_to_netcdf

  • Remove instrument_loc from tsv2dict.product_dict and create_netcdf.make_product_netcdf as per deprecation policy.

  • Increase minimum version of python to 3.10

2.5.2

  • Replace numpy.in1d with numpy.isin as numpy deprecated the former.

  • Add Python 3.14 support

2.5.1

  • Fix bug in create_netcdf.make_netcdf where the platform attribute was not being added back to the FileInfo class object after being formatted, resulting in the wrong value being used by create_netcdf.add_attributes for the platform global attribute.

2.5.0

  • Replaced using instrument_dict dictionary from tsv2dict.instrument_dict in various create netcdf functions with using FileInfo class from file_info. This class better contains the information needed and removes the complexity of the dictionary where different levels of nesting could contain different types of data, which meant IDE plugins relying on type hints to provide information often gave unhelpful messages.

    • Class enables more information to be contained within one entity, and to be clearly labelled.

    • Use of the instrument_dict is therefore being deprecated, along with any additional paramters needed to certain functions which are now all contained within the FileInfo class. Use of instrument_dict and all additional paramters will be removed in version 2.7.0.

  • Type hints have been added.

  • remove_empty_variables.get_product_variables_metadata now accepts a tag argument.

  • Dimensionless variables can now be added to the netCDF file (although a warning message will print).

  • Options for chunking, compression and shuffling of variable data have been added.

  • Information for instrument data is now retrieved from new GitHub repository for instrument data.

  • Added util.change_qc_flags function to enable user-defined quality control flag values and meanings.

  • return_open option in functions in create_netcdf has been removed.

2.4.0

  • Added option to overwrite platform used in file name and global attribute - platform attribute to create_netcdf.main and create_netcdf.make_product_netcdf.

  • Deprecating use of instrument_loc in tsv2dict.product_dict and create_netcdf.make_product_netcdf - use platform instead. instrument_loc will be removed in version 2.6.0.

  • Added options for metadata files in different file formats, including the option to specify the data type of the value of the attribute - this supercedes the update to numbers in metadata in version 2.3.2.

  • Updated default for return_open argument to True (see revision in version 2.3.0 for more information).

2.3.2

  • Corrected how microseconds were being treated by util.get_times

  • Numbers in metadata can be neatly added as strings to global attributes by surrounding them with single quotes, for example ‘1.2’ in the metadata CSV file. Numbers not surrounded by single quotes are still treated as integers or floats.

2.3.1

  • Added package version number to text in the history global attribute.

  • util.get_times returns day_of_year as a list rather than an array, in line with other times returned.

2.3.0

  • Dropped support for Python 3.7, added support for Python 3.12

  • Added History and Deprecations page to documentation.

  • Error raised (with option for warning instead) when using util.update_variable to add data to Quality Control variable if that data includes values not in the flag_values variable attribute.

  • Added deprecation to create_netcdf.main, create_netcdf.make_netcdf, and create_netcdf.make_product_netcdf, for closing the netCDF file after initial creation and population. As of version 2.5.0, these functions will all return an open netCDF file, or a list containing open netCDF files in the case of the function creating multiple files, e.g. multiple data products. This behaviour can be used from version 2.3.0 by passing return_open=True to these functions. As of version 2.4.0, return_open=True will be the default option, with the previous behaviour available by passing return_open=False. In version 2.5.0, the behaviour of return_open=False will be removed.

  • Added option to use locally saved tsv files rather than reading from GitHub.

Deprecation Policy

Through the life of software, it is very likely parts of the package will have to be changed and altered in such a way the user will have to make small changes to their work in order to keep up with changes in the software. While these deprecations are kept to a minimum, they cannot be altogether avoided. This policy states how this package aims to deal with changes and deprecation of code.

If something in the package is to be deprecated and replaced:

  1. A DeprecationWarning must be raised when the code that will be removed will be executed, which must mention in which version of the package that thing will no longer work or be available. That version must be at least 2 minor versions later (i.e. code that raises a deprecation warning added in 2.3.x cannot be removed until 2.5.0 at the earliest).

  2. If possible, a way of using the new code should be made available simultaneously. In this case, the deprecation warning must include information to the user on how to use the new code. If this is not possible, the deprecation warning should last for at least 3 minor versions (i.e. if first raised in 2.3.x, it should not be removed until 2.6.0), with beta versions of the package published with the new code.

  3. If the change in the code can be contained within a boolean argument to a function, then that argument must default to the original code when the deprecation warning is first added, and removed in the version of the package where the code is deprecated, but it is allowed to change the default option to the new code in an intermediate release while the old version of the code is still available within the function. This change of default option must happen in the next minor version release at the earliest, with the code removed at least one further minor release later (i.e. if a deprecation is added in 2.3.x and is covered by a boolean argument, in 2.3.x that boolean argument must default to the original code, in 2.4.x it can default to original or new, and then the argument and original code can be removed from 2.5.0). If this default option is changed before the deprecated code is removed, this must be mentioned in the deprecation warning before the change happens (i.e. in the example above, in version 2.3.x), and in the deprecation warning afterwards (i.e. in 2.4.x) it must state how to use the original code.

  4. Deprecations must be added to the documentation, including what is being deprecated, which version the deprecation warning was first introduced, in which version the original code will be removed, and all information on how to use both original and new versions of the code in the intervening releases.

  5. All references to minor release versions must be superseded by a major release version, for example if a deprecation warning introduced in 2.3.x states something will be removed in 2.5.0, then that thing must be removed in 3.0.0, even if it comes out before 2.5.0 (which presumably would then not be published).