Eliminate garage.misc

[ryanjulian]

garage.misc is a dumping ground for code which should mostly be organized somewhere else. There's also a huge list of "utils" modules hiding around everywhere, many duplicating code in the others.

Here we will audit all the code in garage.misc to determined whether it should be

1. Deleted, because it's terrifying (e.g. stub) or badly-designed
2. Replaced by a library dependency
3. Moved to its own top-level module or into some existing module (e.g. garage.logger)
4. Begrudgingly accepted for now, and generate an issue to rewrite it
5. Left alone

We will algo audit all the utils modules to have as few as possible.

[naeioi]

@ryanjulian Any suggestion of people I can talk to on stub()? I have no clear idea of what it is used for right now.

[ryanjulian]

This is distinct from stub(). I will comment on that issue #239

[ryanjulian]

Audit of garage.misc

Module	Description	Verdict	Destination Module	PRs
autoargs	Decorator for injecting command line arguments directly into constructors	🛑 Remove	N/A	#573
console	Console and filesystem utilities, plus some meta-programming nonsense	🚧 Refactor	garage.logger	#464
ext	?	?	?
instrument	Actually the experiment runner	🚧 Refactor	garage.experiment	#386
krylov	?	?	?
logger	API for the logging facility	🚧 Refactor	garage.logger	#464
mako_utils	Snippets for mako models	🚧 Refactor	rlworkgroup/metaworlds	#488
meta	Literally empy	🛑 Remove	N/A	#492
nb_utils	Tools for processing experiments with Jupyter notebook	🚧 Refactor	garage.experiment.nb_utils	#493
overrides	Decorator for annotating and verifying overided methods	📚 Replace with library	N/A
resolve	Class resolution tools	Remove	rlworkgroup/metaworlds	#488
special	?	?	?
tabulate	Builds tables for printing to the console	📚 Replace with library	N/A	#464
tensor_utils	?	?	?
tensorboard_output	TensorBoard sink for logging	🚧 Refactor	garage.logger	#419
viewer_2d	General-purpose 2D image-based plotter in PyGame	🛑 Remove	N/A	#492
prog_bar_counter.py	Paints progress bars to stdout	🚧 Refactor	garage.logger

Notes

autoargs

"Command line arguments anywhere" is a tempting pattern, but IME this often escalates into entry points with giant numbers of irrelevant, impossible-to-understand command line args. Unless you have a very special application architecture, it's probably better for libraries to be configured in code and not on the command line.

I prefer if we force people to specify their command line args only at the entry point, the old-fashioned away. autoargs injects arbitrary new arguments into __init__() without forcing you to modify the callsite, making constructors hard to read. If we wanted functionality like this we could probably find it in any number of Python command line arguments libraries.

console

This appears to contain mostly utilities used by the logger, plus some odds and ends. It includes raw console printing, colorizing of log messages, mkdir -p in Python, data structures for logs, and a utility for querying Y/N from the user.

Almost all of this could be replaced by a library or moved into the logger module.

Console printing

Use logging from stdlib or

Logger data structures

Possibly a part of a future logger

Colorization

https://github.com/tartley/colorama
https://github.com/magmax/colorize
https://github.com/dslackw/colored

Meta-programming nonsense

Get rid of it

mkdir -p

AFAICT this is now implemented in the Python 3 stdlib and we no longer need our own implementation. It may have been missing in Python 2.

logger

API for the logging facility. This is more bespoke than it needs to be, and a lot of the console logging can be replaced with the Python logger. This module also handles checkpointing. TBD whether we should split checkpointing into its own module.

overrides

This is a method decorator for import-time checking that a method which claims to be overriding a superclass method is actually doing that. It is slightly less-relevant if we refactor to make good use of ABCs, but I think still useful to have.

The current copy is a straight copy/paste of a pip library with some code commented out. See: https://github.com/mkorpela/overrides

[ryanjulian]

Updated view

Module	Description	Verdict	Destination Module	PRs
console	Console and filesystem utilities, plus some meta-programming nonsense	🚧 Refactor	???
ext	Random seed plus various utilities	🚧 Refactor	garage.experiment, garage.tf.optimizers	#578
krylov	Math utils for an optimization procedure	???	garage.math?
overrides	Decorator for annotating and verifying overided methods	📚 Replace with library	N/A
special	Lots of math utilities	???	?
tensor_utils	More math utilities, mostly tensor manipulation	?	?
prog_bar_counter.py	Paints progress bars to stdout	📚 Replace with library	click