# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['gsfpy']

package_data = \
{'': ['*'], 'gsfpy': ['libgsf/*']}

setup_kwargs = {
    'name': 'gsfpy',
    'version': '1.5.1',
    'description': 'Python wrapper for the C implementation of the Generic Sensor Format library.',
    'long_description': '# gsfpy - Generic Sensor Format for Python\n\n![Python Package](https://github.com/UKHO/gsfpy/workflows/Python%20Package/badge.svg)\n\nPython wrapper for the C implementation of the Generic Sensor Format library.\n\n- Free software: MIT license\n\n## Features\n\n- gsfpy.bindings provides wrappers for all GSFlib functions, including I/O, utility and info functions.\n  Minor exceptions are noted in the sections below.\n\n- For added convenience the gsfpy top level package provides the following higher level abstractions:\n  - `open_gsf()`\n  - `GsfFile` (class)\n  - `GsfFile.read()`\n  - `GsfFile.get_number_records()`\n  - `GsfFile.seek()`\n  - `GsfFile.write()`\n  - `GsfFile.close()`\n\n## Install\n\n```shell script\npip install git+ssh://git@github.com/UKHO/gsfpy.git@master\n```\n\n```shell script\npip install git+https://github.com/UKHO/gsfpy.git@master\n```\n\n## Examples of usage\n\n### Open/close/read from a GSF file\n\n```python\nfrom ctypes import string_at\n\nfrom gsfpy import open_gsf\nfrom gsfpy.enums import RecordType\n\nwith open_gsf("path/to/file.gsf") as gsf_file:\n    # Note - file is closed automatically upon exiting \'with\' block\n    _, record = gsf_file.read(RecordType.GSF_RECORD_COMMENT)\n\n    # Note use of ctypes.string_at() to access POINTER(c_char) contents of\n    # c_gsfComment.comment field.\n    print(string_at(record.comment.comment))\n```\n\n### Write to a GSF file\n\n```python\nfrom ctypes import c_int, create_string_buffer\n\nfrom gsfpy import open_gsf\nfrom gsfpy.enums import FileMode, RecordType\nfrom gsfpy.gsfRecords import c_gsfRecords\n\ncomment = "My comment"\n\n# Initialize the contents of the record that will be written.\n# Note use of ctypes.create_string_buffer() to set POINTER(c_char) contents.\nrecord = c_gsfRecords()\nrecord.comment.comment_time.tvsec = c_int(1000)\nrecord.comment.comment_length = c_int(len(comment))\nrecord.comment.comment = create_string_buffer(comment)\n\nwith open_gsf("path/to/file.gsf", mode=FileMode.GSF_CREATE) as gsf_file:\n    gsf_file.write(record, RecordType.GSF_RECORD_COMMENT)\n```\n\n### Copy GSF records\n\n```python\nfrom ctypes import byref, c_int, pointer\n\nimport gsfpy\nfrom gsfpy.enums import FileMode, RecordType\nfrom gsfpy.gsfDataID import c_gsfDataID\nfrom gsfpy.gsfRecords import c_gsfRecords\n\n\n# This example uses gsfpy.bindings to illustrate use of the lower level functions\nfile_handle = c_int(0)\ndata_id = c_gsfDataID()\nsource_records = c_gsfRecords()\ntarget_records = c_gsfRecords()\n\nret_val_open = gsfpy.bindings.gsfOpen(\n    "path/to/file.gsf", FileMode.GSF_READONLY, byref(file_handle)\n)\n\n# Note use of ctypes.byref() as a shorthand way of passing POINTER parameters to\n# the underlying foreign function call. ctypes.pointer() may also be used.\nbytes_read = gsfpy.bindings.gsfRead(\n    file_handle,\n    RecordType.GSF_RECORD_COMMENT,\n    byref(data_id),\n    byref(source_records),\n)\n\n# Note use of pointer() rather than byref() when passing parameters to\n# gsfCopyRecords(). Implementation of this function is in Python as calling\n# the native underlying function causes memory ownership clashes. byref()\n# is only suitable for passing parameters to foreign function calls (see\n# ctypes docs).\nret_val_cpy = gsfpy.bindings.gsfCopyRecords(\n    pointer(target_records), pointer(source_records)\n)\nret_val_close = gsfpy.bindings.gsfClose(file_handle)\n```\n\n### Troubleshoot\n\n```python\nimport gsfpy\n\n# The gsfIntError() and gsfStringError() functions are useful for\n# diagnostics. They return an error code and corresponding error\n# message, respectively.\nretValIntError = gsfpy.bindings.gsfIntError()\nretValStringError = gsfpy.bindings.gsfStringError()\nprint(retValStringError)\n```\n\n## Notes on implementation\n\n### gsfPrintError()\n\nThe `gsfPrintError()` method of GSFlib is not implemented as there is no\nFILE* equivalent in Python. Use `gsfStringError()` instead - this will\ngive the same error message, which can then be written to file as\nrequired.\n\n### gsfCopyRecords() and gsfFree()\n\n`gsfFree()` the sibling method to `gsfCopyRecord()` in GSFlib, used to\ndeallocate memory assigned by the library but managed by the calling\napplication, is not required by gsfpy as memory allocation and\ndeallocation is handled by ctypes. `gsfFree()` is therefore omitted from\nthe package.\n\n### gsf_register_progress_callback()\n\nImplementation of the GSFlib function\n`gsf_register_progress_callback()` is not applicable for gsfpy as the\nDISPLAY_SPINNER macro was not defined during compilation. It is\ntherefore omitted from the package.\n\n## Generic Sensor Format Documentation\n\nGeneric Sensor Format specification: see e.g.\n<https://github.com/schwehr/generic-sensor-format/blob/master/doc/GSF_lib_03-06.pdf>\n\nGeneric Sensor Format C library v3.06 specification: see e.g.\n<https://github.com/schwehr/generic-sensor-format/blob/master/doc/GSF_spec_03-06.pdf>\n\nMore recent versions of these documents can be downloaded from the\n[Leidos](https://www.leidos.com/products/ocean-marine) website.\n\n## Dev Setup\n\n[Ensure Poetry is installed before proceeding](https://python-poetry.org/docs/#installation)\n\n### Poetry (Recommended)\nBy default Poetry will create it\'s own virtual environment using your system\'s Python. [This feature can be disabled.](https://python-poetry.org/docs/faq/#i-dont-want-poetry-to-manage-my-virtual-environments-can-i-disable-it)\n\n```shell script\ngit clone git@github.com:UKHO/gsfpy.git\ncd gsfpy\npoetry install\n```\n\n### Pyenv\nA good choice if you want to run a version of Python different than available through your system\'s package manager\n\n```shell script\ngit clone git@github.com:UKHO/gsfpy.git\ncd gsfpy\npyenv install 3.8.3\npyenv virtualenv 3.8.3 gsfpy\npyenv local gsfpy\npoetry install\n```\n\n### Virtualenv\n\n```shell script\ngit clone git@github.com:UKHO/gsfpy.git\nvirtualenv gsfpy (--always-copy)\ncd gsfpy\nsource bin/activate\npoetry install\n```\n\n## Run tests\n\n```shell script\nmake test\n```\n\n## Notes on Security\n\nSome known concerns relating to the underlying GSFlib C library are\ndocumented at <https://github.com/dwcaress/MB-System/issues/368> and\n<https://github.com/schwehr/generic-sensor-format/issues>. Note that\ngsfpy simply wraps GSFlib and does not purport to stop or mitigate these\npotential vulnerabilities. It is left to the authors of applications\ncalling gsfpy to assess these risks and mitigate where deemed necessary.\n\nGSF data processed using gsfpy should be sourced from reliable providers\nand checked for integrity where possible.\n\nPlease also refer to the LICENSE file for the terms of use of gsfpy.\n\n## Credits\n\n`libgsf03-08.so` was built from the\n[Leidos](https://www.leidos.com/products/ocean-marine) C code using the\nMakefile in [UKHO/libgsf](https://github.com/UKHO/libgsf)\n\nThis package was created with\n[Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the\n[UKHO/cookiecutter-pypackage](https://github.com/UKHO/cookiecutter-pypackage)\nproject template.\n\n## Related Projects\n\nAlso see [schwehr/generic-sensor-format](https://github.com/schwehr/generic-sensor-format/)\n',
    'author': 'UK Hydrographic Office',
    'author_email': 'datascienceandengineering@ukho.gov.uk',
    'maintainer': None,
    'maintainer_email': None,
    'url': 'https://github.com/UKHO/gsfpy',
    'packages': packages,
    'package_data': package_data,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
