dbf_light 1.0.1__py3-none-any.whl

dbf_light/__init__.py

@@ -0,0 +1,4 @@
+from .light import Dbf, open_db
+
+
+VERSION = '1.0.1'

dbf_light/_base.py

@@ -0,0 +1,37 @@
+
+import struct
+
+
+class Definition:
+
+    _definition = ()
+    _struct_rule = ''
+    _struct_size = None
+    _names = []
+
+    def __init__(self, data):
+        self.data = data
+
+    @classmethod
+    def init_cache(cls):
+        names = []
+        rules = []
+
+        for name, rule in cls._definition:
+            names.append(name)
+            rules.append(rule)
+
+        cls._names = names
+        rule = '<' + ''.join(rules)
+        cls._struct_rule = rule
+        cls._struct_size = struct.calcsize(rule)
+
+    @classmethod
+    def _unpack(cls, raw):
+        unpacked = struct.unpack(cls._struct_rule, raw)
+        return dict(zip(cls._names, unpacked, strict=False))
+
+    @classmethod
+    def from_file(cls, fileobj):
+        data = fileobj.read(cls._struct_size)
+        return cls(cls._unpack(data))

dbf_light/cast.py

@@ -0,0 +1,68 @@
+
+from datetime import datetime
+from decimal import Decimal
+
+
+def parse_string(field, val):
+    return val.decode(field.encoding).strip()
+
+
+def parse_date(field, val):
+    val = parse_string(field, val)
+
+    if not val:
+        return None
+
+    return datetime.strptime(val, '%Y%m%d').date()
+
+
+def parse_numeric(field, val):
+
+    val = parse_string(field, val)
+
+    if not val:
+        return None
+
+    if field.data['decimal_count']:
+        val = Decimal(val)
+    else:
+        val = int(val)
+
+    return val
+
+
+def parse_float(field, val):
+    val = parse_string(field, val)
+
+    if not val:
+        return None
+
+    return float(val)
+
+
+def parse_bool(field, val):
+    val = parse_string(field, val).lower()
+
+    if not val or val == '?':
+        return None
+
+    return val in {'t', 'y'}
+
+
+def parse_memo(field, val):
+    val = parse_string(field, val).lower()
+
+    if not val:
+        return None
+
+    return int(val)
+
+
+CAST_MAP = {
+    b'C': parse_string,
+    b'D': parse_date,
+    b'N': parse_numeric,
+    b'F': parse_float,
+    b'L': parse_bool,
+    b'M': parse_memo,
+}

dbf_light/cli.py

@@ -0,0 +1,65 @@
+import click
+
+from dbf_light import VERSION, open_db
+
+arg_db = click.argument('db', type=click.Path(dir_okay=False))
+opt_encoding = click.option('--encoding', help='Encoding used by DB')
+opt_zipped = click.option(
+    '--zip', help='Zip filename containing DBF', type=click.Path(exists=True, dir_okay=False))
+opt_nocase = click.option(
+    '-i', '--case-insensitive', help='Do not honor DB filename case', is_flag=True)
+
+
+@click.group()
+@click.version_option(version=VERSION)
+def entry_point():
+    """dbf_light command line utilities."""
+
+
+@entry_point.command()
+@arg_db
+@opt_encoding
+@click.option('--no-limit', help='Do not limit number of rows to output.', is_flag=True)
+@opt_zipped
+@opt_nocase
+def show(db, encoding, no_limit, zip, case_insensitive):
+    """Show .dbf file contents (rows)."""
+
+    limit = 15
+
+    if no_limit:
+        limit = float('inf')
+
+    with open_db(db, zip, encoding=encoding, case_sensitive=not case_insensitive) as dbf:
+        for idx, row in enumerate(dbf, 1):
+            click.secho('')
+
+            for key, val in row._asdict().items():
+                click.secho(f'  {key}: {val}')
+
+            if idx == limit:
+                click.secho(
+                    f'Note: Output is limited to {limit} rows. Use --no-limit option to bypass.', fg='red')
+                break
+
+
+@entry_point.command()
+@arg_db
+@opt_zipped
+@opt_nocase
+def describe(db, zip, case_insensitive):
+    """Show .dbf file statistics."""
+
+    with open_db(db, zip, case_sensitive=not case_insensitive) as dbf:
+        click.secho(f'Rows count: {dbf.prolog.records_count}')
+        click.secho('Fields:')
+        for field in dbf.fields:
+            click.secho(f'  {field.type}: {field}')
+
+
+def main():
+    entry_point(obj={})
+
+
+if __name__ == '__main__':
+    main()

dbf_light/definitions.py

@@ -0,0 +1,171 @@
+
+import struct
+
+from ._base import Definition
+from .cast import CAST_MAP
+from .utils import bytes_to_int
+
+CODE_PAGES = {
+    1: 'cp437',
+    2: 'cp850',
+    3: 'cp1252',
+    87: 'ascii',
+    101: 'cp866',
+    201: 'cp1251',
+}
+
+
+class Field(Definition):
+
+    _definition = (
+        ('name', '11s'),
+        ('type', 'c'),
+        ('reserved1', '4s'),
+        ('len', 'c'),
+        ('decimal_count', 'B'),
+        ('reserved2', '13s'),
+        ('mdx', '?'),  # dBASE IV only
+    )
+
+    @classmethod
+    def from_file(cls, fileobj, name_lower=True, encoding=None):
+        field = super().from_file(fileobj)
+
+        if name_lower:
+            field.set_name(field.data['name'].lower())
+
+        field.encoding = encoding
+
+        return field
+
+    def __init__(self, data):
+        super().__init__(data)
+        data = self.data
+
+        data['name'] = data['name'].decode().rstrip('\0')
+
+        self.name = data['name']
+        self.len = bytes_to_int(data['len'])
+        self.type = data['type']
+
+    def __str__(self):
+        return self.name
+
+    def set_name(self, name):
+        self.name = self.data['name'] = name
+
+    def cast(self, value):
+        return CAST_MAP.get(self.data['type'], lambda field, val: val)(self, value)
+
+
+class Prolog(Definition):
+
+    cls_field = Field
+
+    _definition = (
+        ('y', 'c'),
+        ('m', 'c'),
+        ('d', 'c'),
+        ('records', 'I'),
+        ('len_head', 'H'),
+        ('len_rec', 'H'),
+        ('reserved1', '2s'),
+        ('incomplete_tr', '?'),  # dBASE IV
+        ('encrypted', '?'),  # dBASE IV
+        ('reserved2', '12s'),  # Reserved for multi-user processing.
+        ('mdx_exists', '?'),
+        ('code_page', 'B'),  # dBASE IV, Visual FoxPro, XBase
+        ('reserved3', '2s'),
+    )
+
+    def __init__(self, data):
+        super().__init__(data)
+
+        data = self.data
+
+        self.records_count = data['records']
+
+        # +2 -> 1 byte for signature + 1 step
+        count = (data['len_head'] - (self._struct_size+2)) / self.cls_field._struct_size
+
+        assert count.is_integer(), 'Unexpected records count. It seems that file format is misinterpreted.'
+
+        self.fields_count = int(count)
+
+    @property
+    def encoding(self):
+        return CODE_PAGES.get(self.data['code_page'])
+
+
+class FieldFoxpro(Field):
+
+    _definition = (
+        ('name', '32s'),
+        ('type', 'c'),
+        ('len', 'c'),
+        ('decimal_count', 'B'),
+        ('reserved1', '2s'),
+        ('mdx', '?'),
+        ('reserved2', '2s'),
+        ('autoinc', 'I'),
+        ('reserved2', '4s'),
+    )
+
+
+class PrologFoxpro(Prolog):
+
+    cls_field = FieldFoxpro
+
+    _definition = (
+        *Prolog._definition,
+        ('language_driver', '32s'),
+        ('reserved4', '4s'),
+    )
+
+
+Prolog.init_cache()
+Field.init_cache()
+
+PrologFoxpro.init_cache()
+FieldFoxpro.init_cache()
+
+
+def get_format_description(fileobj):
+    """
+
+    https://www.loc.gov/preservation/digital/formats/fdd/fdd000325.shtml
+    https://www.clicketyclick.dk/databases/xbase/format/dbf.html#DBF_STRUCT
+
+    http://www.autopark.ru/ASBProgrammerGuide/DBFSTRUC.HTM
+
+    Сигнатура	СУБД	Описание
+    3	0x03	00000011	dBASE III, dBASE IV, dBASE 5, dBASE 7, FoxPro, FoxBASE+	Таблица без memo-полей
+    4	0x04	00000100	dBASE 7	Таблица без memo-полей
+    67	0x43	01000011	dBASE IV, dBASE 5	SQL-таблица dBASE IV без memo-полей
+    99	0x63	01100011	dBASE IV, dBASE 5	Системная SQL-таблица dBASE IV без memo-полей
+    131	0x83	10000011	dBASE III, FoxBASE+, FoxPro	Таблица с memo-полями .DBT
+    139	0x8B	10001011	dBASE IV, dBASE 5	Таблица с memo-полями .DBT формата dBASE IV
+    140	0x8C	10001100	dBASE 7	Таблица с memo-полями .DBT формата dBASE IV
+    203	0xE5	11100101	SMT	Таблица с memo-полями .SMT
+    235	0xEB	11101011	dBASE IV, dBASE 5	Системная SQL-таблица dBASE IV с memo-полями .DBT
+
+    Custom signatures:
+
+    2	0x02	00000010	FoxBASE	Таблица без memo-полей
+    48	0x30	00110000	Visual FoxPro	Таблица (признак наличия memo-поля .FPT не предусмотрен )
+    49	0x31	00110001	Visual FoxPro	Таблица с автоинкрементными полями
+    203	0xCB	11001011	dBASE IV, dBASE 5	SQL-таблица dBASE IV с memo-полями .DBT
+    245	0xF5	11110101	FoxPro	Таблица с memo-полями .FPT
+    251	0xFB	11111011	FoxBASE	Таблица с memo-полями .???
+
+    :param fileobj:
+    :rtype: tuple(Prolog, bytes)
+
+    """
+    signature = struct.unpack('<B', fileobj.read(1))[0]
+
+    if signature in {48, 49}:  # pragma: nocover
+        # todo return PrologFoxpro when it's debugged (records count error exists).
+        raise NotImplementedError('FoxPro dbf support is not implemented.')
+
+    return Prolog, signature

dbf_light/exceptions.py

@@ -0,0 +1,4 @@
+
+
+class DbfException(Exception):
+    """Base exception."""

dbf_light/light.py

@@ -0,0 +1,195 @@
+
+import struct
+from pathlib import Path
+from collections import namedtuple
+from contextlib import contextmanager
+from functools import partial
+from zipfile import ZipFile
+
+from .utils import string_types, pick_name
+from .definitions import get_format_description
+from .exceptions import DbfException
+
+
+class Dbf:
+    """Represents data from .dbf file."""
+
+    def __init__(self, fileobj, encoding=None, fieldnames_lower=True):
+        """
+        :param fileobj: Python file-like object containing .dbf file data.
+
+        :param str|unicode encoding: Encoding used by DB.
+            This will be used if there's no encoding information in the DB itself.
+
+        :param bool fieldnames_lower: Lowercase field names.
+
+        """
+        self._fileobj = fileobj
+        self._lower = fieldnames_lower
+
+        cls_prolog, self.signature = get_format_description(fileobj)
+
+        self.cls_prolog = cls_prolog
+        self.cls_field = cls_prolog.cls_field
+
+        prolog = self.cls_prolog.from_file(fileobj)
+        self.prolog = prolog
+
+        if encoding is None:
+            encoding = prolog.encoding
+
+        self._encoding = encoding or 'cp866'
+
+        self.fields, self.cls_row = self._read_fields()
+
+    def __iter__(self):
+        return iter(self.iter_rows())
+
+    @classmethod
+    @contextmanager
+    def open(cls, dbfile, encoding=None, fieldnames_lower=True, case_sensitive=True):
+        """Context manager. Allows opening a .dbf file.
+
+        .. code-block::
+
+            with Dbf.open('some.dbf') as dbf:
+                ...
+
+        :param str|unicode|file dbfile: .dbf filepath or a file-like object.
+
+        :param str|unicode encoding: Encoding used by DB.
+            This will be used if there's no encoding information in the DB itself.
+
+        :param bool fieldnames_lower: Lowercase field names.
+
+        :param bool case_sensitive: Whether DB filename is case sensitive.
+
+        :rtype: Dbf
+        """
+        if not case_sensitive:
+            if isinstance(dbfile, string_types):
+                dbfile = pick_name(dbfile, Path(dbfile).parent.iterdir())
+
+        with Path(dbfile).open('rb') as f:
+            yield cls(f, encoding=encoding, fieldnames_lower=fieldnames_lower)
+
+    @classmethod
+    @contextmanager
+    def open_zip(cls, dbname, zipped, encoding=None, fieldnames_lower=True, case_sensitive=True):
+        """Context manager. Allows opening a .dbf file from zip archive.
+
+        .. code-block::
+
+            with Dbf.open_zip('some.dbf', 'myarch.zip') as dbf:
+                ...
+
+        :param str|unicode dbname: .dbf file name
+
+        :param str|unicode|file zipped: .zip file path or a file-like object.
+
+        :param str|unicode encoding: Encoding used by DB.
+            This will be used if there's no encoding information in the DB itself.
+
+        :param bool fieldnames_lower: Lowercase field names.
+
+        :param bool case_sensitive: Whether DB filename is case sensitive.
+
+        :rtype: Dbf
+        """
+        with ZipFile(zipped, 'r') as zip_:
+
+            if not case_sensitive:
+                dbname = pick_name(dbname, zip_.namelist())
+
+            with zip_.open(dbname) as f:
+                yield cls(f, encoding=encoding, fieldnames_lower=fieldnames_lower)
+
+    def iter_rows(self):
+        """Generator reading .dbf row one by one.
+
+        Yields named tuple Row object.
+
+        :rtype: Row
+        """
+        fileobj = self._fileobj
+        cls_row = self.cls_row
+        fields = self.fields
+
+        for _ in range(self.prolog.records_count):
+            data = fileobj.read(1)
+
+            marker = struct.unpack('<1s', data)[0]
+            is_deleted = marker == b'*'
+
+            if is_deleted:
+                # Skip the record bytes to keep the stream in sync.
+                fileobj.read(sum(field.len for field in fields))
+                continue
+
+            row_values = []
+            for field in fields:
+                val = field.cast(fileobj.read(field.len))
+                row_values.append(val)
+
+            yield cls_row(*row_values)
+
+    def _read_fields(self):
+        fh = self._fileobj
+        field_from_file = partial(self.cls_field.from_file, name_lower=self._lower, encoding=self._encoding)
+
+        fields = []
+        field_names = []
+        for _ in range(self.prolog.fields_count):
+            field = field_from_file(fh)  # type: Field
+            name = field.name
+
+            if name in field_names:
+                # Handle duplicates.
+                name = name + '_'
+                field.set_name(name)
+
+            fields.append(field)
+            field_names.append(name)
+
+        terminator = struct.unpack('<c', fh.read(1))[0]
+
+        if terminator != b'\r':
+            raise DbfException(
+                'Header termination byte not found. '
+                f'Seems to be an unsupported format. Signature: {self.signature}')
+
+        cls_row = namedtuple('Row', field_names)
+
+        return fields, cls_row
+
+
+@contextmanager
+def open_db(db, zipped=None, encoding=None, fieldnames_lower=True, case_sensitive=True):
+    """Context manager. Allows reading DBF file (maybe even from zip).
+
+    :param str|unicode|file db: .dbf file name or a file-like object.
+
+    :param str|unicode zipped: .zip file path or a file-like object.
+
+    :param str|unicode encoding: Encoding used by DB.
+        This will be used if there's no encoding information in the DB itself.
+
+    :param bool fieldnames_lower: Lowercase field names.
+
+    :param bool case_sensitive: Whether DB filename is case sensitive.
+
+    :rtype: Dbf
+    """
+    kwargs = {
+        'encoding': encoding,
+        'fieldnames_lower': fieldnames_lower,
+        'case_sensitive': case_sensitive,
+    }
+
+    if zipped:
+        with Dbf.open_zip(db, zipped, **kwargs) as dbf:
+            yield dbf
+
+    else:
+        with Dbf.open(db, **kwargs) as dbf:
+            yield dbf

dbf_light/utils.py

@@ -0,0 +1,25 @@
+import codecs
+from pathlib import Path
+
+string_types = str,
+
+
+def bytes_to_int(val):
+    return int(codecs.encode(val, 'hex'), 16)
+
+
+def pick_name(filename, candidates):
+    filedir = Path(filename).parent
+    name_lower = Path(filename).name.lower()
+    name_candidate = None
+
+    for name in candidates:
+
+        if name_lower == Path(name).name.lower():
+            name_candidate = str(filedir / name)
+            break
+
+    if name_candidate:
+        filename = name_candidate
+
+    return filename

dbf_light-1.0.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: dbf_light
+Version: 1.0.1
+Summary: Light and easy DBF reader
+Project-URL: Homepage, https://github.com/idlesign/dbf_light
+Author-email: Igor Starikov <idlesign@yandex.ru>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: dbf,reader,xbase
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Provides-Extra: cli
+Requires-Dist: click; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# dbf_light
+
+<https://github.com/idlesign/dbf_light>
+
+[![release](https://img.shields.io/pypi/v/dbf_light.svg)](https://pypi.python.org/pypi/dbf_light)
+[![lic](https://img.shields.io/pypi/l/dbf_light.svg)](https://pypi.python.org/pypi/dbf_light)
+[![coverage](https://img.shields.io/coveralls/idlesign/dbf_light/master.svg)](https://coveralls.io/r/idlesign/dbf_light)
+
+## Description
+
+*Light and easy DBF reader*
+
+No fancy stuff, just DBF reading for most common format versions.
+
+* Uses `namedtuple` for row representation and iterative row reading to minimize memory usage;
+* Works fine with cyrillic (supports KLADR and CBRF databases);
+* Reads .dbf from zip files.
+
+## API
+
+```python
+from dbf_light import Dbf
+
+
+with Dbf.open('some.dbf') as dbf:
+
+    for field in dbf.fields:
+        print('Field: %s' % field)
+
+    print('Rows (%s):' % dbf.prolog.records_count)
+
+    for row in dbf:
+        print(row)
+
+# Read `some.dbf` from zip (ignoring filename case):
+with Dbf.open_zip('some.dbf', 'here/myarch.zip', case_sensitive=False) as dbf:
+    ...
+```
+
+## CLI
+
+Requires `click` package (can be installed with: `pip install dbf_light[cli]`).
+
+```shell
+$ dbf_light describe myfile.dbf
+$ dbf_light show myfile.dbf
+```

dbf_light-1.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+dbf_light/__init__.py,sha256=qsrGnXM_fD2CYQpT4uPYRIkUMovCkGMRSmgNKSNBOiI,52
+dbf_light/_base.py,sha256=5yMCFJ37RTHt4HbhAUL63CuwXytlf-8ELaZP43iBHRY,804
+dbf_light/cast.py,sha256=LrN4VePnLSivROLK5bK09DI_ghh4150lurNgNbHf4pc,1076
+dbf_light/cli.py,sha256=-HFmItVLptvNCGUuZW53mfNuv6mcSzz_yCdhW7kBGVU,1775
+dbf_light/definitions.py,sha256=qX_A7lJDXyhtWhTr20HlT0eWgRyVpqDarO4ZJ2XNNoQ,4908
+dbf_light/exceptions.py,sha256=JaBVZRNCrqoelKhoF-kYIp-1bJB8oJS8_MQkyddCTZ8,59
+dbf_light/light.py,sha256=TP4xN50kCsX77v7Ldi7_Xo19Ye13Y0oUmK3ZAs71vvA,5865
+dbf_light/utils.py,sha256=gzleSaCDQr08To0FHO598TVqpY_bYJ4RVRNgnbzxwYU,503
+dbf_light-1.0.1.dist-info/METADATA,sha256=2f_-N8BPLgthNX30RGYDIs3z3Pws4yd2wL_iVDpDUAQ,2160
+dbf_light-1.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dbf_light-1.0.1.dist-info/entry_points.txt,sha256=lRvm2Wf09GsjloiOeIxJGi3ELMHH9Vd8jQOF2X-eJVk,49
+dbf_light-1.0.1.dist-info/licenses/LICENSE,sha256=CcFIaRyMMZFt-LjYesCkntdv51hrxgOWbuzgD3jhLl4,1502
+dbf_light-1.0.1.dist-info/RECORD,,

dbf_light-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dbf_light-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dbf_light = dbf_light.cli:main

dbf_light-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2018-2026, Igor `idle sign` Starikov
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the dbf_light nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+