python-clinic / notes.txt

Full commit

allow comment marker itself to not be at column 0
    output code will be at this indent also

write iterator for body of file
    yields verbatim sections
    yields code sections
    handles checking checksums

allow first line to not be at column 0
    however that establishes the "column 0" indent for the entire
    rest of the body

    (this will allow you to use in python scripts and have indent,
    otherwise I'd have to require)

    this also allows using in nested code in C where it makes
    sense to indent to the level of code below

    * so, therefore, strip whitespace from beginning of marker?
        * not quite. preserve whitespace from the beginning of marker
          and indent output by that much.

    string is the "<...>" from a Python function definition "def foo <...>:"
    use ast.parse
    specifically allow "/)" (and remove the "/") but it must match "/)" at the end or ")/:"
        (if there are two, good luck!)
        then explicitly make all arguments positional-only
    build up using use ast.literal_eval

class methods should support METH_NOARGS and METH_O with special outputters

proposed change to Python internals:
    right now there's no way to specify the docstring for __init__ and __new__
    we propose that we allow PyMethodDef entries for special methods
        and if they're present we look up their 
        they should be marked somehow
            either a new METH_DONTUSE
            or their function pointer should be NULL
            (or both)

should we ever allow tabs inside the DSL?  Right now we don't allow them
anywhere, including the docstrings.

dmitry sends email:
    do we preserve *all* the metadata information from clinic in the shared
    library? having it in the shared library would be way great for IDEs.

what about annotation:
    how about just an object such that the argument must pass isinstance(argument, o)

clean up bytecode documentation
    use c struct for oparg:
        LOAD_CONST { uint16_t index; }
        MAKE_FUNCTION { uint16_t annotation:16; uint8_t kwonly_defaults; uint8_t positional_defaults; }

    use FORTH stack effect notation for stack effect
        LOAD_CONST ( -- const )
        STORE_NAME ( value -- )