Release Notes for PyCIFRW-4.4
=============================

The ValidCifFile class has been deprecated and will be removed in the
next release.

Changes since 4.3
=================

* Fixed Windows BOM handling
* Work-around for Python 2.7 bug triggered on import (Pavol Juhas)
* Nested save frames no longer accepted when reading non-STAR formats
* CifFile.py filename changed to Ciffile_module.py to avoid class-name ambiguity
* Many Python 3 fixes and improvements (Pavol Juhas)
* `permissive` option added to CIF input to try latin1 encoding as a fallback 
* Bug fixes:
  - datanames in blocks that have been read in from a file can once again 
    have their values changed
  - AddToLoop did not replace looped datanames correctly

Changes since 4.2
=================

* Fixed bugs in fast merging
* Improved DDLm import behaviour
* Improved templating of semicolon-delimited strings
* Added non-standard hash functions to dREL
* Adjusted DDLm CIF dictionary usage to conform to recent changes
* first_block() returns a single block from the file, not necessarily the
  first one in the file, or the first one added to the CifFile object.
* All strings returned by methods are of type unicode.
* Single source for Python2 and Python3

Changes since 4.1.1
===================

* Up to two orders of magnitude improvement in reading speed
  for large files (several Mb). Note that PyCIFRW reads the
  entire file into memory, so you must have sufficient RAM.

* Continuous bugfixes and improvements to dREL system
  - Allow multiple dREL methods per definition
  - Detect and handle recursion in dREL methods

* Understands DDLm use of _import.get to merge dictionaries

* Experimental DDLm attributes for category construction

* Fixed bug in embedded triple-quoted string interpretation

* Output block order defaults to input block order

Incompatible changes (since 3.0 series, unchanged since 4.1)
============================================================

* Function "validate" has been renamed to Validate for consistency
* Nested loops (only allowed in STAR files) are no longer supported
* Merging of datablocks in 'overlay' mode has been removed. This is
  relevant only for dictionary merging.
* The package now installs in a separate Python site-packages directory. 
  called 'CifFile'. It should thus be imported using 'import CifFile' or 
  'from CifFile import CifFile'.  This may differ from earlier versions.
* A single-item loop can no longer be created using the form cf['_dataname'] = [1,2,3,4]
  To get the old behaviour, create the CifBlock with 'compat_mode = True'.
* The line folding protocol is always used when writing CIF files. This is
  only invoked if you have lines longer than 2048 characters (or your specified
  maximum length).
* The text prefix protocol introduced in CIF2.0 is always used when writing. 
  This is only invoked if a string contains the character sequence '\n;'
* The text prefix protocol and line folding protocol are detected and 
  transparently removed from text values when reading.

Python 3 notes
==============

In moving to unified Python2/3 source for version 4.3, all strings
returned by CifFile and StarFile methods are of type unicode in Python
2.  Please create an issue on Bitbucket if this causes breakage in
your software.

* The semantics of key(), items() and values() have not changed for
CifFile and CifBlock objects, despite the Python 3 dictionary
semantics requiring them to be iterators rather than lists.

* In the original Python 2 version, the top-level `CifFile` module
imported everything from the `CifFile.py` and `StarFile.py`
modules. This meant that it was sufficient for your code to include
`from CifFile import x`, where x is anything defined in CifFile.py or
StarFile.py.  This has been replicated in Python 3 by explicitly
importing those classes and functions in CifFile_module.py and
StarFile.py required for the tests to succeed. If your code uses a
function not included in the tests (note that all classes and
therefore their methods are included) you will need to refer to it as
`CifFile.CifFile_module.x` (for a function named `x` in
`CifFile_module.py`).

* Python 3 conversion relied heavily on getting the 170 unit tests to
complete successfully.  These tests cover about 80% of the code. If
your code happens to trigger errors in the remaining code, please create
an issue.  The code that is not covered well is generally DDL1/2
validation code or unusual error conditions.

Deprecated methods
==================

* AddCifItem.  This unnecessarily convoluted and mind-bending way of
adding a whole loop all at once in a single tuple has been deprecated.
Just assign dataname values using the usual square brackets and then
call CreateLoop with the datanames that belong in a single loop.

* AddToLoop. Assign individual values and then call AddLoopName for each

* ValidCifFile (whole class). This appears to be unused. 
