From a6b6712d6a312f8e839212ea246a896391c90abc Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 14 Aug 2015 23:00:04 +0200 Subject: [PATCH] deprecate the numeric --compression argument, rename null compression to none, update CHANGES --- CHANGES.rst | 32 ++++++++++++++++++++++++++++++++ borg/archiver.py | 14 +++++--------- borg/compress.pyx | 10 +++++----- borg/helpers.py | 12 +++--------- borg/key.py | 2 +- borg/testsuite/compress.py | 10 +++++----- borg/testsuite/helpers.py | 11 +++-------- 7 files changed, 54 insertions(+), 37 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index b333ba48..7245371d 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,38 @@ Borg Changelog ============== +Compression branch +------------------ + +Compatibility notes: + +- the new compression code is very compatible: as long as you stay with zlib + compression, older borg releases will still be able to read data from a + repo/archive made with the new code (note: this is not the case for the + default "none" compression, use "zlib,0" if you want a "no compression" mode + that can be read by older borg). Also the new code is able to read repos and + archives made with older borg versions (for all zlib levels 0..9). + +Deprecations: + +- --compression N (with N being a number, as in 0.24) is deprecated. + We keep the --compression 0..9 for now to not break scripts, but it is + deprecated and will be removed later, so better fix your scripts now: + --compression 0 (as in 0.24) is the same as --compression zlib,0 (now). + BUT: if you do not want compression, you rather want --compression none + (which is the default). + --compression 1 (in 0.24) is the same as --compression zlib,1 (now) + --compression 9 (in 0.24) is the same as --compression zlib,9 (now) + +New features: + +- create --compression none (default, means: do not compress, just pass through + data "as is". this is more efficient than zlib level 0 as used in borg 0.24) +- create --compression lz4 (super-fast, but not very high compression) + Please note that borgbackup needs lz4 library as additional requirement. +- create --compression zlib,N (slower, higher compression, default for N is 6) +- create --compression lzma,N (slowest, highest compression, default N is 6) + Version 0.24.0 -------------- diff --git a/borg/archiver.py b/borg/archiver.py index 768dc536..1f0dc1d3 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -668,17 +668,13 @@ Type "Yes I am sure" if you understand this and want to continue.\n""") metavar='CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE', help='specify the chunker parameters. default: %d,%d,%d,%d' % CHUNKER_PARAMS) subparser.add_argument('-C', '--compression', dest='compression', - type=CompressionSpec, default=dict(name='null'), metavar='COMPRESSION', - help='select compression algorithm and level, by giving a number: ' - '0 == no compression [default], ' - '1..9 == zlib level 1..9, ' - '10 == lz4, ' - '20-29 == lzma level 0..9.' - 'Alternatively, you can also give a name and optionally additional args: ' - 'null == no compression, ' + type=CompressionSpec, default=dict(name='none'), metavar='COMPRESSION', + help='select compression algorithm (and level): ' + 'none == no compression (default), ' + 'lz4 == lz4, ' 'zlib == zlib (default level 6), ' 'zlib,0 .. zlib,9 == zlib (with level 0..9), ' - 'lz4 == lz4, ' + 'lzma == lzma (default level 6), ' 'lzma,0 .. lzma,9 == lzma (with level 0..9).') subparser.add_argument('archive', metavar='ARCHIVE', type=location_validator(archive=True), diff --git a/borg/compress.pyx b/borg/compress.pyx index c1bdeff8..2285b55d 100644 --- a/borg/compress.pyx +++ b/borg/compress.pyx @@ -35,12 +35,12 @@ cdef class CompressorBase: return data[2:] -class CNULL(CompressorBase): +class CNONE(CompressorBase): """ - null compression, just pass through data + none - no compression, just pass through data """ ID = b'\x00\x00' - name = 'null' + name = 'none' def compress(self, data): return super().compress(data) @@ -161,12 +161,12 @@ class ZLIB(CompressorBase): COMPRESSOR_TABLE = { - CNULL.name: CNULL, + CNONE.name: CNONE, LZ4.name: LZ4, ZLIB.name: ZLIB, LZMA.name: LZMA, } -COMPRESSOR_LIST = [LZ4, CNULL, ZLIB, LZMA, ] # check fast stuff first +COMPRESSOR_LIST = [LZ4, CNONE, ZLIB, LZMA, ] # check fast stuff first def get_compressor(name, **kwargs): cls = COMPRESSOR_TABLE[name] diff --git a/borg/helpers.py b/borg/helpers.py index 020c263e..8643166f 100644 --- a/borg/helpers.py +++ b/borg/helpers.py @@ -295,20 +295,14 @@ def CompressionSpec(s): compression = int(compression) if count > 1: raise ValueError - # it is just --compression N - if compression == 0: - return dict(name='null') - if 1 <= compression <= 9: + # DEPRECATED: it is just --compression N + if 0 <= compression <= 9: return dict(name='zlib', level=compression) - if compression == 10: - return dict(name='lz4') - if 20 <= compression <= 29: - return dict(name='lzma', level=compression-20) raise ValueError except ValueError: # --compression algo[,...] name = compression - if name in ('null', 'lz4', ): + if name in ('none', 'lz4', ): return dict(name=name) if name in ('zlib', 'lzma', ): if count < 2: diff --git a/borg/key.py b/borg/key.py index fcf08358..7067a445 100644 --- a/borg/key.py +++ b/borg/key.py @@ -68,7 +68,7 @@ class KeyBase: self.TYPE_STR = bytes([self.TYPE]) self.repository = repository self.target = None # key location file path / repo obj - self.compressor = Compressor('null', buffer=COMPR_BUFFER) + self.compressor = Compressor('none', buffer=COMPR_BUFFER) def id_hash(self, data): """Return HMAC hash using the "id" HMAC key diff --git a/borg/testsuite/compress.py b/borg/testsuite/compress.py index 6d7319c1..8019925b 100644 --- a/borg/testsuite/compress.py +++ b/borg/testsuite/compress.py @@ -6,7 +6,7 @@ except ImportError: import pytest -from ..compress import get_compressor, Compressor, CNULL, ZLIB, LZ4 +from ..compress import get_compressor, Compressor, CNONE, ZLIB, LZ4 buffer = bytes(2**16) @@ -15,8 +15,8 @@ params = dict(name='zlib', level=6, buffer=buffer) def test_get_compressor(): - c = get_compressor(name='null') - assert isinstance(c, CNULL) + c = get_compressor(name='none') + assert isinstance(c, CNONE) c = get_compressor(name='lz4', buffer=buffer) assert isinstance(c, LZ4) c = get_compressor(name='zlib') @@ -26,7 +26,7 @@ def test_get_compressor(): def test_cnull(): - c = get_compressor(name='null') + c = get_compressor(name='none') cdata = c.compress(data) assert len(cdata) > len(data) assert data in cdata # it's not compressed and just in there 1:1 @@ -83,7 +83,7 @@ def test_zlib_compat(): def test_compressor(): params_list = [ - dict(name='null', buffer=buffer), + dict(name='none', buffer=buffer), dict(name='lz4', buffer=buffer), dict(name='zlib', level=0, buffer=buffer), dict(name='zlib', level=6, buffer=buffer), diff --git a/borg/testsuite/helpers.py b/borg/testsuite/helpers.py index bb2400a9..76bafb5b 100644 --- a/borg/testsuite/helpers.py +++ b/borg/testsuite/helpers.py @@ -108,17 +108,12 @@ class PatternTestCase(BaseTestCase): def test_compression_specs(): with pytest.raises(ValueError): CompressionSpec('') - assert CompressionSpec('0') == dict(name='null') + assert CompressionSpec('0') == dict(name='zlib', level=0) assert CompressionSpec('1') == dict(name='zlib', level=1) assert CompressionSpec('9') == dict(name='zlib', level=9) - assert CompressionSpec('10') == dict(name='lz4') with pytest.raises(ValueError): - CompressionSpec('11') - assert CompressionSpec('20') == dict(name='lzma', level=0) - assert CompressionSpec('29') == dict(name='lzma', level=9) - with pytest.raises(ValueError): - CompressionSpec('30') - assert CompressionSpec('null') == dict(name='null') + CompressionSpec('10') + assert CompressionSpec('none') == dict(name='none') assert CompressionSpec('lz4') == dict(name='lz4') assert CompressionSpec('zlib') == dict(name='zlib', level=6) assert CompressionSpec('zlib,0') == dict(name='zlib', level=0)