Provides several utilities for handling I/O
This library is currently still under development. The API will likely undergo significant changes that may break any code you write with it. The documentation will fall out of sync with the updates regularly until development slows down. Use it at your own risk.
Provides several utilities for handling I/O:
IOHandler
classargparse.ArgumentParser()
. Must be used as a context manager, and while in scope the Argument.add()
method will act equivalent to ArgumentParser.add_argument()
.IOHandler.process()
(equivalent to ArgumentParser.parse_args()
) returns a subtypes.Dict
holding the argument values if no callback is provided to the IOHandler()
constructor, otherwise it passes on the return value of the callback function, which will be passed a Dict
as its single positional argument.RunMode
Enum
) RunMode.SMART
will attempt to choose the appropriate run-mode for the situation.RunMode.COMMANDLINE
argparse is used under-the-hood to process the sys.argv
arguments, but with additional features and custom-built help interface that is more
readable (and way prettier!)RunMode.GUI
, it will programatically build a GUI to collect user input, with widgets picked based on the 'argtype' argument of Argument()
. The argument defaults can be
overriden at point-in-time by passing a dict
of argument name-value pairs directly to IOHandler.process()
. Further calls to IOHandler.process()
will still have the base
defaultsRunMode.PROGRAMMATIC
, the argument values can be passed directly to IOHandler.process()
as a dict
of argument name-value pairsIOHandler.add_subhandler()
will add a new subhandler which will act as a subcommand under RunMode.COMMANDLINE
, and will act as a tabbed sheet under RunMode.GUI
. The handlers
exist in a hierarchy, meaning that arguments passed to all parents on the way to the lowest child sheet (on the gui) or final used subcommand (in the commandline) are still handled.Argument
classThe Argument()
constructor arguments tell the IOHandler how to handle nullability, default values, implicit coercion to the right type, whether the argument is optional,
commandline aliases, conditions, dependencies, etc.
An ArgType
Enum
is provided to be passed to the Argument(argtype=)
constructor argument. This will let the IOHandler
perform type checking and coercion. Currently the
recognized types are:
member | with IOHandler(subtypes=True) | with IOHandler(subtypes=False) |
---|---|---|
STRING | subtypes.Str | str |
INTEGER | int | int |
FLOAT | float | float |
DECIMAL | decimal.Decimal | decimal.Decimal |
BOOLEAN | bool | bool |
LIST | subtypes.List | list |
DICT | subtypes.Dict | dict |
SET | set | set |
PATH | pathlib.Path | pathlib.Path |
FILE | pathmagic.File | pathmagic.File |
DIR | pathmagic.Dir | pathmagic.Dir |
DATETIME | subtypes.DateTime | datetime.datetime |
FRAME | subtypes.Frame | pandas.DataFrame |
Validate
classint
, float
, bool
, str
, list
, set
, dict
,
subtypes.DateTime
, pathlib.Path
, pathmagic.File
, pathmagic.Dir
)Validate.Int
, Validate.Float
, Validate.Bool
, Validate.Str
, Validate.List
, Validate.Set
, Validate.Dict
, Validate.DateTime
, Validate.Path
,
Validate.File
, Validate.Dir
Validator
classesIntegerValidator
, FloatValidator
, BoolValidator
, StringValidator
, ListValidator
, SetValidator
, DictionaryValidator
, DateTimeValidator
,
PathValidator
, FileValidator
, DirValidator
Validate.Int().max_value(7).is_valid(9)
would return False.Validator.add_condition()
ListValidator
and DictionaryValidator
will coerce strings by using eval (safely), rather than coercing a string to a list by calling list()
on itGui
class and its various template subclassesWidgetManager
objects to easily set up a GUI, with the exact internals of the
underlying QT classes abstracted away behind a consistent API. Makes it very quick and easy to set up a simple GUI. Is a thin wrapper around PyQt5.ThreePartGui
class for quickly setting up Horizontal-Vertical-Horizontal guisHTMLGui
class for Rendering HTML in a separate windowWidgetManager
class and its various widget subclassesLabel
, Button
, Checkbox
, CheckBar
, DropDown
, Entry
, Text
, FileSelect
, DirSelect
, Calendar
, DateTimeEdit
,
HtmlDisplay
, ProgressBar
, Table
, ListTable
, DictTable
, WidgetFrame
, HorizontalFrame
, VerticalFrame
WidgetManager.active
, WidgetManager.state
, WidgetManager.text
, and WidgetManager.parent
.Console
classScript
classrepr()
of the script objectprint()
statements to a log file**kwargs
passed to the constructor are stored in the Script.arguments
attributeScript.name
attribute is automatically set to the name of the file the class is defined inIOHandler
, the Script.run_mode
attribute is automatically 'smart' by default, but can be overriden by setting it as a class attributeCache
classdict
for interacting with the items in the cache: Cache.put()
, Cache.get()
, Cache.pop()
, and Cache.setdefault()
Serializer
classLostObject
instancesSecrets
classTo install use pip:
$ pip install pyiotools
Or clone the repo:
$ git clone https://github.com/matthewgdv/iotools.git
$ python setup.py install
Usage examples coming soon.
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Report bugs at https://github.com/matthewgdv/iotools/issues
If you are reporting a bug, please include:
Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement a fix for it.
Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
The repository could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/matthewgdv/iotools/issues.
If you are proposing a new feature:
Before you submit a pull request, check that it meets these guidelines:
If the pull request adds functionality, it should include tests and the docs should be updated. Write docstrings for any functions that are part of the external API, and add the feature to the README.md.
If the pull request fixes a bug, tests should be added proving that the bug has been fixed. However, no update to the docs is necessary for bugfixes.
The pull request should work for the newest version of Python (currently 3.7). Older versions may incidentally work, but are not officially supported.
Inline type hints should be used, with an emphasis on ensuring that introspection and autocompletion tools such as Jedi are able to understand the code wherever possible.
PEP8 guidelines should be followed where possible, but deviations from it where it makes sense and improves legibility are encouraged. The following PEP8 error codes can be safely ignored: E121, E123, E126, E226, E24, E704, W503
This repository intentionally disallows the PEP8 79-character limit. Therefore, any contributions adhering to this convention will be rejected. As a rule of thumb you should endeavor to stay under 200 characters except where going over preserves alignment, or where the line is mostly non-algorythmic code, such as extremely long strings or function calls.