GitLab

- completes migration to new "compress =" keyword argument.

- complete the transition to the context manager based working copy management code.

- shortcut to exit if tmp_path not set so that calling codes don't have to include that test
- make the verbosity messages a little more clear
- remove the verbose parameter, relying instead on self.verbose

- and bump version to 1.7.1

This reverts commit 866c600a.

This patch causes the test suite to fail with

Traceback (most recent call last):
  File "/home/kipp/local/bin/ligolw_print", line 4, in <module>
    __import__('pkg_resources').run_script('python-ligo-lw==1.7.0', 'ligolw_print')
  File "/usr/lib/python3/dist-packages/pkg_resources/__init__.py", line 665, in run_script
    self.require(requires)[0].run_script(script_name, ns)
  File "/usr/lib/python3/dist-packages/pkg_resources/__init__.py", line 1451, in run_script
    raise ResolutionError(
pkg_resources.ResolutionError: Script 'scripts/ligolw_print' not found in metadata at None

- prior to this, compress=None explicitly selected "no compression", and was also the default, and when writing a file it was always necessary to explicitly enable compression if desired.  now:
- compress=None means "select default behaviour", and does not necessarily mean to disable compression
- load_fileobj() and write_fileobj() (and by proxy load_filename(), write_filename(), load_url(), write_url()) accept compress=False to explicitly disable compression.  this is a new keyword argument and does not break backwards compatibility
- load_fileobj() and write_filename() accept compress="auto" to explicitly enable automatic format detection.  this is a new keyword argument and does not break backward compatibility
- load_fileobj()'s compress=None default is to select "auto" mode, which is equivalent to the previous behaviour
- write_filename()'s compress=None default is to select "auto" mode, which is not equivalent to previous behaviour and so breaks compatibility, however, in practice all calling codes include logic to set or clear the (deprecated) gz keyword argument to force compression on or off.  the gz keyword argument is maintained for backwards compatibility and continues to override the compress= keyword argument so this change will have no effect on calling codes

- add .initialized() class method to SearchSummary row type
- port utils.search_summary.append_search_summary() to use new .initialized() method

Distutils and setuptools projects that populate the same namespace
package do not play well together. Setuptools is smart enough to
skip installation of the namespace package's dummy __init__.py file
and its ancillary .pyc or __pycache__ files, but distutils is not.
Distutils projects that use namespace packages are likely to disrupt
package managers that protect against two packages trying to install
the same files.

It is relatively rare these days to find Python projects that use
distutils directly rather than setuptools. In fact, the official
Python standard library documentation for distutils
(https://docs.python.org/3/library/distutils.html) says:

> Most Python users will not want to use this module directly, but
> instead use the cross-version tools maintained by the Python
> Packaging Authority.

Switching python-ligo-lw from distutils to setuptools simplifies
software packaging.

- removes the need to install a hook into the NamedTemporaryFile instance to delete the corresponding -journal file in the event of program termination.  clean-up is the responsibility of the context manager.
- backwards compatibility wrappers are provided
- a small change in calling code is, however, required:  in all calling codes, must change connect(tmpname) to connect(str(tmpname)).  this can be done in advance of the python-ligo-lw release.
- fixes issue #!14
- include set_temp_store_directory() method in context manager, deprecate module-level equivalent

- the default value for the existing "gz" keyward argument is "False", not None, which breaks the error checking the temporary _normalize_compress_kwarg() function.  this patch fixes the error checking, but it's not as good as it used to be because some mistakes can't be tested for.

This is to prepare us to support multiple compression methods
including Zstandard.

See !13.

- rename import for consistency with typical code

- edit the documentation to explain that the file object must be in binary mode.

- do not demonstrate writing a file to stdout.  thanks to the craziness of file io in python 3 this is impossible.

- gets doctests to pass with Python 3 (breaks Python 2)

- unfortunately python 3 makes it impossible to do a byte-for-byte comparison, which the code actually should be able to pass.

- to be used by testsuite to canonicalize XML files

lal is used only for LIGOTimeGPS, and the import is at the point of
use and not at module level. glue is used to provide old ILWD format
support, and glue imports are guarded by if statements. The basic
functionality of python-ligo-lw is still present if lal and glue are
missing, so it is appopriate to describe the relationship using
`Recommends` rather than `Depends`.

On the other hand, LALSuite uses glue pervasively, so LALSuite must
Depend on python-ligo-lw.

This breaks the circular dependency that was a problem in
lscsoft/lalsuite!644.

Glue is not being actively maintained. Tqdm is a very popular and
lightweight progress bar and is nicer than the one in glue anyway.
So many packages use tqdm that the user is likely to already have
it on their system.