psdi-data-conversion 0.0.23__py3-none-any.whl

psdi_data_conversion-0.0.23.dist-info/METADATA

@@ -0,0 +1,663 @@
+Metadata-Version: 2.1
+Name: psdi_data_conversion
+Version: 0.0.23
+Summary: Chemistry file format conversion service, provided by PSDI
+Project-URL: Homepage, https://psdidev2.azurewebsites.net/
+Project-URL: Documentation, https://psdi-uk.github.io/psdi-data-conversion/
+Project-URL: Repository, https://github.com/PSDI-UK/psdi-data-conversion
+Project-URL: Issues, https://github.com/PSDI-UK/psdi-data-conversion/issues
+Project-URL: Changelog, https://github.com/PSDI-UK/psdi-data-conversion/blob/main/CHANGELOG.md
+Project-URL: Download, https://github.com/PSDI-UK/psdi-data-conversion/releases/latest
+Author: Ray Whorley, Don Cruickshank, Tom Underwood
+Author-email: Samantha Pearman-Kanza <s.pearman-kanza@soton.ac.uk>, Bryan Gillis <7204836+brgillis@users.noreply.github.com>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Keywords: atomsk,chemistry,conversion,flask,openbabel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: File Formats
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.12
+Requires-Dist: openbabel-wheel
+Requires-Dist: py
+Provides-Extra: doc
+Requires-Dist: pdoc3; extra == 'doc'
+Provides-Extra: gui
+Requires-Dist: flask; extra == 'gui'
+Requires-Dist: requests; extra == 'gui'
+Provides-Extra: gui-test
+Requires-Dist: coverage; extra == 'gui-test'
+Requires-Dist: flask; extra == 'gui-test'
+Requires-Dist: pytest; extra == 'gui-test'
+Requires-Dist: requests; extra == 'gui-test'
+Requires-Dist: selenium; extra == 'gui-test'
+Requires-Dist: webdriver-manager; extra == 'gui-test'
+Provides-Extra: test
+Requires-Dist: coverage; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# PSDI Data Conversion
+
+Version: Pre-release 2024-02-27
+
+This is the repository for the PSDI PF2 Chemistry File Format Conversion project. The goal of this project is to provide utilities to assist in converting files between the many different file formats used in chemistry, providing information on what converters are available for a given conversion and the expected quality of it, and providing multiple interfaces to perform these conversions. These interfaces are:
+
+- Online web service, available at https://psdidev2.azurewebsites.net
+- Version of the web app you can download and run locally (e.g. if you need to convert files which exceed the online app's file size limit)
+- Command-line application, to run conversions from a terminal
+- Python library
+
+## Table of Contents
+
+- [Project Structure](#project-structure)
+- [Requirements](#requirements)
+  - [Python](#python)
+  - [Other Dependencies](#other-dependencies)
+- [Command-Line Application](#command-line-application)
+  - [Installation](#installation)
+  - [Execution](#execution)
+    - [Data Conversion](#data-conversion)
+    - [Requesting Information on Possible Conversions](#requesting-information-on-possible-conversions)
+- [Python Library](#python-library)
+  - [Installation](#installation-1)
+  - [Use](#use)
+    - [`run_converter`](#run_converter)
+    - [`get_converter`](#get_converter)
+    - [`constants`](#constants)
+    - [`database`](#database)
+  - [Further Information](#further-information)
+- [Using the Online Conversion Service](#using-the-online-conversion-service)
+- [Running the Python/Flask app locally](#running-the-pythonflask-app-locally)
+  - [Installation and Setup](#installation-and-setup)
+  - [Running the App](#running-the-app)
+- [Testing](#testing)
+
+## Project Structure
+
+- `.github`
+  - `workflows`
+    - (Automated workflows for various tasks related to project maintenance)
+- `deploy`
+  - (Files used as part of the deployment to STFC infrastructure)
+- `psdi_data_conversion` (Primary source directory)
+  - `bin`
+    - (Precompiled binaries for running file format converters)
+  - `static` (Static code and assets for the web app)
+    - `content`
+      - (HTML assets for the web app)
+    - `downloads` (created by app.py if not extant)
+    - `img`
+      - (image assets for the web app)
+    - `javascript`
+      - (JavaScript code for the web app)
+    - `styles`
+      - (CSS stylesheets for the web app)
+    - `uploads` (created by app.py if not extant)
+  - `templates`
+    - (HTML assets rendered by Flask for the web app)
+  - `__init.py__`
+  - (Python packages, modules, and scripts)
+- `scripts`
+  - (Scripts used for project maintenance)
+- `test_data`
+  - (Files used for testing the project)
+- `tests`
+  - (Unit tests for the project)
+- `CHANGELOG.md` (Updates since initial public release)
+- `CONTRIBUTING.md` (Guidelines and information for contributors to the project)
+- `DOCKERFILE` (Dockerfile for image containerising PSDI's data conversion service)
+- `LICENSE` (Apache Licence version 2.0)
+- `pyproject.toml` (Python project metadata and settings)
+- `README.md` (This file)
+- `requirements.txt` (Requirements for the Azure web app deployment of this project)
+- `run_local.sh` (Helper script to run the web app locally)
+- `startup.sh` (Startup script for the Azure web app)
+
+## Requirements
+
+### Python
+
+Any local installation of this project requires Python 3.12 or greater. The best way to do this is dependant on your system, and you are likely to find the best tailored instructions by searching the web for e.g. "install Python 3.12 <your-os-or-distribution>". Some standard options are:
+
+For Windows and MacOS: Download and run the installer for the latest version from the official site: https://www.python.org/downloads/
+
+For Linux systems, Python is most readily installed with your distribution's package manager. For Ubuntu/Debian-based systems, this is `apt`, and the following series of commands can be used to install the latest version of Python compatible with your system:
+
+```bash
+sudo apt update # Make sure the package manager has access to the latest versions of all packages
+sudo apt upgrade # Update all installed packages
+sudo apt install python3 # Install the latest possible version of Python
+```
+
+Check the version of Python installed with one of the following:
+
+```bash
+python --version
+python3 --version
+```
+
+Usually `python` will be set up as an alias to python3, but if you already have an older version installed on your system, this might not be the case. You may be able to set this behaviour up by installing the `python-is-python3` package:
+
+```bash
+sudo apt install python-is-python3
+```
+
+Also check that this process installed Python's package manager, `pip`, on your system:
+
+```bash
+pip --version
+```
+
+If it didn't, you can manually install it with:
+
+```bash
+sudo apt install python3-pip
+```
+
+If this doesn't work, or the version installed is too low, an alternative is to install Python via the Anaconda package manager. For this, see the guide here: https://www.askpython.com/python/examples/install-python-with-conda. If you already have an earlier version of Python installed with Anaconda, you can install and activate a newer version with a command such as:
+
+```bash
+conda create --name converter python=3.12 anaconda # Where 'converter' is a possible conda environment name
+conda activate converter
+```
+
+You can also install a newer version of Python if you wish by substituting "3.12" in the above with e.g. "3.13".
+
+### Other Dependencies
+
+This project depends on other projects available via pip, which will be installed automatically as required:
+
+Required for all installations (`pip install .`):
+
+- `py`
+- `openbabel-wheel`
+
+Required to run the web app locally for a GUI experience (`pip install .[gui]`):
+
+- `Flask`
+- `requests`
+
+Required to run unit tests (`pip install .[test]`):
+
+- `pytest`
+- `coverage`
+
+Required to run unit tests on the web app (`pip install .[gui-test]`):
+
+- (all web app and test requirements listed above)
+- `selenium`
+- `webdriver_manager`
+
+In addition to the dependencies listed above, this project uses the assets made public by PSDI's common style project at https://github.com/PSDI-UK/psdi-common-style. The latest versions of these assets are copied to this project periodically (using the scripts in the `scripts` directory). In case a future release of these assets causes a breaking change in this project, the file `fetch-common-style.conf` can be modified to set a previous fixed version to download and use until this project is updated to work with the latest version of the assets.
+
+## Command-Line Application
+
+### Installation
+
+The CLA and Python library are installed together. This package is not yet available on PyPI, and so must be installed locally. This can be done most easily with:
+
+```bash
+pip install .
+```
+
+executed from this project's directory. You can also replace the '.' in this command with the path to this project's directory to install it from elsewhere.
+
+Depending on your system, it may not be possible to install packages in this manner without creating a virtual environment to do so in. You can do this by first installing the `venv` module for Python3 with e.g.:
+
+```bash
+sudo apt install python3-venv # Or equivalent for your distribution
+```
+
+You can then create and activate a virtual environment with:
+
+```bash
+python -m venv .venv # ".venv" here can be replaced with any name you desire for the virtual environment
+source .venv/bin/activate
+```
+
+You should then be able to install this project. When you wish to deactivate the virtual environment, you can do so with the `deactivate` command.
+
+### Execution
+
+Once installed, the command-line script `psdi-data-convert` will be made available, which can be called to either perform a data conversion or to get information about possible conversions and converters. You can see the full options for it by calling:
+
+```bash
+psdi-data-convert -h
+```
+
+This script has two modes of execution: Data conversion, and requesting information on possible conversions and converters.
+
+#### Data Conversion
+
+Data conversion is the default mode of the script. At its most basic, the syntax for it will look like:
+
+```bash
+psdi-data-convert filename.ext1 -t ext2
+```
+
+This will convert the file 'filename.ext1' to format 'ext2' using the default converter (Open Babel). A list of files can also be provided, and they will each be converted in turn.
+
+The full possible syntax for the script is:
+
+```
+psdi-data-convert <input file 1> [<input file 2> <input file 3> ...] -t/--to <output format> [-f/--from <input file
+format>] [-i/--in <input file location>] [-o/--out <location for output files>] [-w/--with <converter>] [--delete-input]
+[--from-flags '<flags to be provided to the converter for reading input>'] [--to-flags '<flags to be provided to the
+converter for writing output>'] [--from-options '<options to be provided to the converter for reading input>']
+[--to-options '<options to be provided to the converter for writing output>'] [--coord-gen <coordinate generation
+options] [-s/--strict] [--nc/--no-check] [-q/--quiet] [-g/--log-file <log file name] [--log-level <level>] [--log-mode
+<mode>]
+```
+
+Call `psdi-data-convert -h` for details on each of these options.
+
+#### Requesting Information on Possible Conversions
+
+The script can also be used to get information on possible conversions by providing the `-l/--list` argument:
+
+```bash
+psdi-data-convert -l
+```
+
+Without any further arguments, the script will list converters available for use and file formats supported by at least one converter. More detailed information about a specific converter or conversion can be obtained through providing more information.
+
+To get more information about a converter, call:
+
+```
+psdi-data-convert -l <converter name>
+```
+
+This will print general information on this converter, including what flags and options it accepts for all conversions, plus a table of what file formats it can handle for input and output.
+
+To get information about which converters can handle a given conversion, call:
+
+```
+psdi-data-convert -l -f <input format> -t <output format>
+```
+
+This will provide a list of converters which can handle this conversion, and notes on the degree of success for each.
+
+To get information on input/output flags and options a converter supports for given input/output file formats, call:
+
+```
+psdi-data-convert -l <converter name> [-f <input format>] [-t <output format>]
+```
+
+If an input format is provided, information on input flags and options accepted by the converter for this format will be provided, and similar for if an output format is provided.
+
+## Python Library
+
+### Installation
+
+The CLA and Python library are installed together. See the [above instructions for installing the CLA](#installation), which will also install the Python library.
+
+### Use
+
+Once installed, this project's library can be imported through the following within Python:
+
+```python
+import psdi_data_conversion
+```
+
+The most useful modules and functions within this package to know about are:
+
+- `psdi_data_conversion`
+  - `converter`
+    - `run_converter`
+  - `constants`
+  - `database`
+
+#### `run_converter`
+
+This is the standard method to run a file conversion. This method may be imported via:
+
+```python
+from psdi_data_conversion.converter import run_converter
+```
+
+For a simple conversion, this can be used via:
+
+```python
+run_converter(filename, to_format, name=name, data=data)
+```
+
+Where `filename` is the name of the file to convert (either fully-qualified or relative to the current directory), `to_format` is the desired format to convert to (e.g. `"pdb"`), `name` is the name of the converter to use (default "Open Babel"), and `data` is a dict of any extra information required by the specific converter being used, such as flags for how to read/write input/output files (default empty dict).
+
+See the method's documentation via `help(run_converter)` after importing it for further details on usage.
+
+#### `constants`
+
+This package defines most constants used in the package. It may be imported via:
+
+```python
+from psdi_data_conversion import constants
+```
+
+Of the constants not defined in this package, the most notable are the names of available converters. Each converter has its own name defined in its module within the `psdi_data_conversion.converters` package (e.g. `psdi_data_conversion.converters.atomsk.CONVERTER_ATO`), and these are compiled within the `psdi_data_conversion.converter` module into:
+
+- `D_SUPPORTED_CONVERTERS` - A dict which relates the names of all converters supported by this package to their classes
+- `D_REGISTERED_CONVERTERS` - As above, but limited to those converters which can be run on the current machine (e.g. a converter may require a precompiled binary which is only available for certain platforms, and hence it will be in the "supported" dict but not the "registered" dict)
+- `L_SUPPORTED_CONVERTERS`/`L_REGISTERED_CONVERTERS` - Lists of the names of supported/registered converters
+
+#### `database`
+
+The `database` module provides classes and methods to interface with the database of converters, file formats, and known possible conversions. This database is distributed with the project at `psdi_data_conversion/static/data/data.json`, but isn't user-friendly to read. The methods provided in this module provide a more user-friendly way to make common queries from the database:
+
+- `get_converter_info` - This method takes the name of a converter and returns an object containing the general information about it stored in the database (note that this doesn't include file formats it can handle - use the `get_possible_formats` method for that)
+- `get_format_info` - This method takes the name of a file format (its extension) and returns an object containing the general information about it stored in the database
+- `get_degree_of_success` - This method takes the name of a converter, the name of an input file format (its extension), and the name of an output file format, and provides the degree of success for this conversion (`None` if not possible, otherwise a string describing it)
+- `get_possible_converters` - This method takes the names of an input and output file format, and returns a list of converters which can perform the desired conversion and their degree of success
+- `get_possible_formats` - This method takes the name of a converter and returns a list of input formats it can accept and a list of output formats it can produce. While it's usually a safe bet that a converter can handle any combination between these lists, it's best to make sure that it can with the `get_degree_of_success` method
+- `get_in_format_args` and `get_out_format_args` - These methods take the name of a converter and the name of an input/output file format, and return a list of info on flags accepted by the converter when using this format for input/output
+- `get_conversion_quality` - Provides information on the quality of a conversion from one format to another with a given converter. If conversion isn't possible, returns `None`. Otherwise returns a short string describing the quality of the conversion, a string providing information on possible issues with the conversion, and a dict providing details on property support between the input and output formats
+
+### Further Information
+
+The code documentation for the Python library is published online at https://psdi-uk.github.io/psdi-data-conversion/. Information on modules, classes, and methods in the package can also be obtained through standard Python methods such as `help()` and `dir()`.
+
+## Using the Online Conversion Service
+
+Enter https://psdidev2.azurewebsites.net in a browser. Guidance on usage is given on each page of the website.
+
+## Running the Python/Flask app locally
+
+### Installation and Setup
+
+Install the package and its requirements, including the optional requirements used to run the GUI locally, by executing the following command from this project's directory:
+
+```bash
+pip install .'[gui]'
+```
+
+If your system does not allow installs in this manner, it may be necessary to set up a virtual environment. See the instructions in the [command-line application installation](#installation) section above for how to do that, and then try to install again once you've set one up and activated it.
+
+If you've cloned this repository, you can use the `run_local.sh` bash script to run the application. Otherwise (e.g. if you've installed from a wheel or PyPI), copy and paste the following into a script:
+
+```bash
+#!/bin/bash
+
+# The envvar MAX_FILESIZE can be used to set the maximum allowed filesize in MB - 0 indicates no maximum
+if [ -z $MAX_FILESIZE ]; then
+  export MAX_FILESIZE=0
+fi
+
+# Logging control - "full" sets server-style logging, which is necessary to produce the output logs with the expected
+# names. This should not be changed, or else errors will occur
+export LOG_MODE=full
+
+# The level to log at. Leave blank for defaults, which logs at INFO level for user output and ERROR level for the server
+# log and stdout. If set to a different value here (e.g. DEBUG), all these channels will be set to that level
+export LOG_LEVEL=
+
+# The envvar SERVICE_MODE can be set to "true" to make this behave as if it's running as the public web service -
+# uncomment the following line to enable that
+# export SERVICE_MODE=true
+
+# Uncomment the following line to enable debug mode
+# export FLASK_ENV=development
+
+# Execute a local run of the application from the proper path
+
+PACKAGE_PATH=`python -c "import psdi_data_conversion; print(psdi_data_conversion.__path__[0])"`
+cd $PACKAGE_PATH/..
+python -m flask --app psdi_data_conversion/app.py run
+```
+
+If desired, you can modify the environmental variables set in this script to modify the operation - see the comments on each for details.
+
+### Running the App
+
+Run the `run_local.sh` script to start the server. You can then access the website by going to <http://127.0.0.1:5000> in a browser (this will also be printed in the terminal, and you can CTRL+click it there to open it in your default browser). Guidance for using the app is given on each page of it.
+
+In case of problems when using Chrome, try opening Chrome from the command line:
+open -a "Google Chrome.app" --args --allow-file-access-from-files
+
+## Extending Functionality
+
+The Python library and CLA are written to make it easy to extend the functionality of this package to use other file format converters. This can be done by downloading or cloning the project's source from it's GitHub Repository (https://github.com/PSDI-UK/psdi-data-conversion), editing the code to add your converter following the guidance in the "[Adding File Format Converters](https://github.com/PSDI-UK/psdi-data-conversion/blob/main/CONTRIBUTING.md#adding-file-format-converters)" section of CONTRIBUTING.md to integrate it with the Python code, and installing the modified package on your system via:
+
+```bash
+pip install --editable .'[test]'
+```
+
+(This command uses the `--editable` option and optional `test` dependencies to ease the process of testing and debugging your changes.)
+
+Note that when adding a converter in this manner, information on its possible conversions will not be added to the database, and so these will not show up when you run the CLA with the `-l/--list` option. You will also need to add the `--nc/--no-check` option when running conversions to skip the database check that the conversion is allowed.
+
+## Testing
+
+To test the CLA and Python library, install the optional testing requirements locally (ideally within a virtual environment) and test with pytest by executing the following commands from this project's directory:
+
+```bash
+pip install .'[test]'
+pytest
+```
+
+To test the local version of the web app, install the GUI testing requirements locally (which also include the standard GUI requirements and standard testing requirements), start the server, and test by executing the GUI test script:
+
+```bash
+pip install .'[gui-test]'
+./run_local.sh & # Start the server for the web app in the background
+cd tests/selenium
+./run.sh
+kill %1 # Stop the web server - it may have a different job ID. If you don't know the job ID, you can alternatively call "fg" to bring the job to the foreground, then type CTRL+c to stop it
+```
+
+## Contributors
+
+- Ray Whorley
+- Don Cruickshank
+- Samantha Pearman-Kanza (s.pearman-kanza@soton.ac.uk)
+- Bryan Gillis (7204836+brgillis@users.noreply.github.com)
+- Tom Underwood
+
+## Funding
+
+PSDI acknowledges the funding support by the EPSRC grants EP/X032701/1, EP/X032663/1 and EP/W032252/1