[CentralOH] Feedback on a New Package

[Joe Joyce]

Thomas,

Thank you for the quick feedback! It's exactly the sort of thing I was
looking for. I've been munching on it the last couple days, thoughts
below.

First -- duh. The instant I looked at the docs after reading your
message, I saw exactly what you're talking about. The links under
"Development" are documents about how to build/test/QA clik itself.
But that is not *at all* clear! (Unless, err... you happened to have
been the one who wrote that section like a month ago and haven't
thought about it much since....)

Second -- sigh. Quickstart/introductory documentation was/is a major
struggle with clik.

> how do I make a --help option or how do I get a filename name as the
> first argument into a function that opens the file

For a real-world program the answer is "just use argparse" -- clik
provides nothing but an extra dependency to hassle with. clik doesn't
really start to help out until/unless the program is more complex
(namely: once it grows subcommands).

So I've felt that, to make a compelling case for clik, the example
code fundamentally has to be complex. That's why the tutorial is
thirteen friggin' steps, and 52m in screencast form.

But that's an unsatsifying answer. Expecting new users to make that
kind of investment of time and mental energy on a first-pass
evaluation is INSANE.

I'm not totally sure what the answer is. But you're right, I need to
bridge that gap.

Also, there is a more specific answer to your example question.
See below :).

import sys

from clik import app, args, parser


def do_a_thing_with_a_filename(filename):
    pass


@app
def myapp():
    """
    This sentence and the next will be between the usage statement and
    the argument docs. If you're familiar with argparse, it's the
    ``description``.

    All the content after the first blank line is shown after the
    argument docs. In argparse terms, it's the ``epilog``. Note that
    argparse will reformat your documentation, so this is not
    a good place for things like examples that require formatting.
    """

    # Note: The -h/--help argument is automatically added by argparse.
    #       clik provides the ``name`` (for the usage statement),
    #       ``description`` and ``epilog`` to argparse. Description
    #       and epilog are taken from the function docstring, as
    #       described above. The ``name`` defaults to the function's
    #       name, but can be overridden by calling the decorator as
    #       follows: @app(name='other-name')

    parser.add_argument(
        '-f',
        '--filename',
        help='filename to pass to the function',
    )

    yield

    if args.filename is None:
        print('please provide a filename', file=sys.stderr)
        yield 1

    do_a_thing_with_a_filename(args.filename)


if __name__ == '__main__':
    myapp.main()


Thanks again for your feedback!
Joe


On Wed, Dec 20, 2017 at 11:25 AM, Thomas Winningham <winningham at gmail.com>
wrote:

> Very minor item from a quick look. The Quick start section seems to be
> about building the project. While exceptionally complete content, I was
> expecting something like a simplified version of the example code, say, how
> do I make a --help option or how do I get a filename name as the first
> argument into a function that opens the file.
>
> Otherwise, nicely done with having all the resources and such as the
> documentation and the package submission all ready to go. Pretty clean and
> clear!!
>
> On Dec 20, 2017 9:23 AM, "Joe Joyce" <joe at decafjoe.com> wrote:
>
> Hello all!
>
> Long time listener, first time caller. Love the show :P.
>
> So -- I built a thing. And if any of you have time over the holiday
> break, I'd appreciate any feedback you have.
>
> The code / docs are in the usual places:
>
> https://github.com/decafjoe/clik
> https://clik.readthedocs.io
> https://pypi.python.org/pypi/clik
>
> There are two "levels" of feedback I'm looking for.
>
> First, I've been in the forest so long on this thing that I'm not sure
> whether the tutorial explains the concepts well, if at all. It all
> makes sense to me, of course, but it's impossible for me to look at it
> with a fresh set of eyes.
>
> So -- not considering whether the library itself sucks -- does the
> tutorial explain things well? Is the pace appropriate? Too much detail
> / too little?
>
> Second, any feedback on the library itself is welcome. This is the
> first "real" thing I've released into the world, but I'll try not to
> be too sensitive! I'm curious (and a honestly a little afraid) about
> what y'all will think.
>
> Thanks, and happy holidays!
> Joe
>
>
> _______________________________________________
> CentralOH mailing list
> CentralOH at python.org
> https://mail.python.org/mailman/listinfo/centraloh
>
>
>
> _______________________________________________
> CentralOH mailing list
> CentralOH at python.org
> https://mail.python.org/mailman/listinfo/centraloh
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/centraloh/attachments/20171223/68a911ae/attachment.html>