From f672c635a276d8d0de53e3e02ecff6ee93c2cc0c Mon Sep 17 00:00:00 2001 From: IAlibay Date: Wed, 15 Jul 2020 14:23:06 +0100 Subject: [PATCH] adds usage docs for file-like objects --- propka/input.py | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/propka/input.py b/propka/input.py index 2929ae3..26e61d5 100644 --- a/propka/input.py +++ b/propka/input.py @@ -38,14 +38,39 @@ def open_file_for_reading(input_file): def read_molecule_file(input_file, mol_container, filename=None): """Read input file or stream (PDB or PROPKA) for a molecular container - Args + Args: input_file: input file to read mol_container: MolecularContainer object - filename: str, optional input filename when using a filestream - Returns + filename (str): optional input filename when using a filestream + + Returns: updated MolecularContainer object - Raises + + Raises: ValuError if invalid input given + + Examples: + There are two main cases for using ``read_molecule_file``. The first + (and most common) is to pass the input file (``input_file``) as a + string which gives the path of the molecule file to be read (here we + also pass a ``MoleculeContainer`` object named ``mol_container``). + + >>> read_molecule_file('test.pdb', mol_container) + + + The other use case is when passing a file-like object, e.g. a + ``StringIO`` class, instance as the input file. In order to decide how + to process ``input_file``, ``read_molecule_file`` requires a file name. + Since file-like objects do not usually have an associated file name, we + must pass a value to the ``filename`` argument. This helps recognise + the file type (based on the extension being either `.pdb` or + `.propka_input`) and also associates that given ``filename`` with the + input MolecularContainer object. + + >>> read_molecule_file(string_io_object, mol_container, + filename='test.pdb') + + """ try: input_path = Path(input_file)