oitnb works around some of black's issues
Homepage Repository PyPI Python
pip install oitnb==0.2.2
The uncompromising code formatter Black
has very many good points, but by design
it is not very flexible. If you cannot accept it as is oitnb
might be an
alternative for you.
In short, on top of Black
's features, oitnb
:
--double
.# fmt: off
at appropriate places. Option --meld
.__init__.py
).oitnb
Work-in-progress/things planned:
--multi-line-unwrap
. (A must
if you write a lot of in-file , dedented, strings with YAML, as e.g.
YAML library developer would.)oitnb
code is directly derived from Black
's and uses many files
as-is.
It can run most of Black
's tests without problems but there is a
handful of errors, which should all have to do with hard-coded
references to Black in both file content and file naming.
extra options: --double
, --meld
, --multi-line-unwrap
oitnb
defaults to single-quotes around strings, if you want to use
the quoting like Black
has use the option --double
option.
--meld
which works like --diff
,
but for the invocation of meld
on the original file and the
reformatted version. meld
allows you to directly edit the left
hand side (original) so you can at that point decide to insert some
# fmt: off
/ # fmt: on
comments around lines, or to abandon
the use of a formatter altogether.
Specifying --multi-line-unwrap
runs an ugly post-processor on the reformatted lines
undoing the rewrite of:
x = yaml.load(""" a: 1 b: 2 """)
into:
x = yaml.load( """ a: 1 b: 2 """ )
The program starts with an empty config dict and tries to read the basic
configuration from oitnb.pon
in the user config dir using
appdirs.user_config_dir
. This adheres to the XDG standard on Linux
(i.e. ~/.config/oitnb)
if no environment variables are set to
change the defaults. That file should contain a valid Python dict
definition ( with {} or dict(), and from this dict
the value
for default
is taken (using safe evaluation) to update the config dict:
dict( default=dict(line_length=666, double=True), )
After that the directory hierarchy up-the-tree is searched until
.git
is found, or .hg
or an __init__.py
file with a module
level definition of _package_data
. That should be a dict and from
there the value for the key oitnb
is taken to update the
config:
_package_data = dict( oitnb=dict(line_length=88), )
oitnb
's __init__.py
has more information there used (without import
-ing!), and
programmatically updated, by other tools:
_package_data = dict( full_package_name='oitnb', version_info=(0, 1, 1), __version__='0.1.1', author='Anthon van der Neut', author_email='a.van.der.neut@ruamel.eu', description="oitnb works around some of black's issues", entry_points='oitnb=oitnb:main', license='MIT', since=2018, status=alpha, package_data={"_oitnb_lib2to3": ["*.txt"]}, install_requires=['click>=6.5', 'attrs>=17.4.0', 'appdirs', 'toml>=0.9.4'], test_suite="_test.test_oitnb", tox=dict( env='36', ), oitnb=dict(line_length=88), ) version_info = _package_data['version_info'] __version__ = _package_data['__version__']
On top of this, any command-line options are used to overrule the config, and then the program is initialised.
Dashes (-) in options are internally replaced by underscore (_), you can use that form as key in dict(op_tion=True). With dashes you would need to use {"op-tion": True}
There is currently no computer wide, setting for defaults, such as
/etc/xdg/oitnb
(is anyone sharing their development machines these
days?).
oitnb
revisionsIf you have an existing project with revision history, and apply
oitnb
to your sources, then diffing between pre- and
post-oitnb
versions is going to be cluttered.
If your application of oitnb
was applied without Internal errors, and if you did
not have to apply # fmt: no
to often, then you can use the
following to get more useful visual diffs using meld
.
The installation of oitnb
includes a minimal utility omeld
,
add this as an external diff tool to your mercurials .hgrc
file:
[extensions] hgext.extdiff = [extdiff] cmd.omeld =
Now you can execute hg omeld -r-4 -r-1
or hg omeld -r-4
(assuming revision -4 was from before applying oitnb
) and
omeld
will run oitnbt
on both temporarily created source
trees, before handing those trees over to meld
. That means
e.g. that any source changes regarding quotes or removal of
superfluous u's from u'' strings, rewrapping, etc. are going to be the same for both
sides of the revisions. Thereby leaving the real code changes in the
diff that meld
presents.
If the omeld tools gets a file or directory as argument that is not
under /tmp
or /var/tmp
, it will not run oitnb
on that
file/directory. If you keep your source tree under /var/tmp
, you are
out of luck: your python will be formatted.
The above approach: check out both (old) revisions trees, code format
them with ``oitnb`` and run a diff, is generic. meld
and mercurial
are just
the tools I use and can easily provide a working setup for.
For git, which in my experience is a bit more difficult to get to understand multiple external difftools, you can do:
alias gomeld='git difftool --extcmd=omeld -y'
and use that alias.
git
seems somewhat more optimised than hg
in that if the current checked out
version of a file is the same as one of the reversions asked, that it
will not make a temporary version (not even if you have to compare
multiple files). Versions before 0.1.4 should therefore not be used
with the above alias, as those may result updated files
in your source tree (which should not break anything, but not be what
you expected).
If you use single-quotes for your strings you are in good company: "People use to really love double quotes. I don't know why.. And as PEP8 has the following to say about quotes around strings:
In Python, single-quoted strings and double-quoted strings are the same. This PEP does not make a recommendation for this. Pick a rule and stick to it.
Googling for Stick to it: continue or confine oneself to doing or using a particular thing.
It is not just the consistency of confining yourself, it is also the long term continuation.
If you have a list of short strings that fit on a line and add one so that it doesn't fit anymore,
you
don't
want
that
to
all
of
a
sudden
force
every
single
element
on a new line. Just putting the added overflow on a new line is good enough in those cases.
The Unicode in the messages might not display in the font
you're using (they did not for me with Inconsolata in my Gnome Terminal). Do you
know what those code-points should show? If not, are you sure that when
using Black
on a different computer, while the person who pays you
for your work looks over your shoulder, that you'll not be embarrassed (or get into
trouble if e.g. they were code-points U+5350 or U+0FD5)?
You might find seeing the SLEEPING FACE (U+1F634), SHORTCAKE (U+1F370), COLLISION SYMBOL (U+1F4A5), BROKEN HEART (U+1F494), SPARKLES (U+2728) interesting for a while. But especially when using a small font in order not to scroll too much the details become blurry and no-fun.
The configurability of Black consists inserting lines in Yet Another Markup Format that adds nothing to the existing spectrum in Yet Another Config File cluttering your project directory.