[Python-ideas] Suggestion for standardized annotations

[Cem Karan]

I've written some sample code that can do the type of annotations that I'm suggesting; is there a particular way that code is shared on the list, or should I just put it on the web somewhere?

On Mar 5, 2014, at 11:46 PM, Greg Ewing <greg.ewing at canterbury.ac.nz> wrote:

> CFK wrote:
>> then it shouldn't be too hard for a project to add its own UUID to the annotation dictionary.
> 
> I can't see what benefit there is in bringing UIIDs into
> the picture.
> 
> If you're suggesting that people write the UUIDs directly
> into their code as literals, that's *not* going to fly.
> It would be appallingly ugly and error-prone.
> 
> The only way to make it usable would be to import the
> UUIDs from somewhere under human-readable names. But then
> there's no need to use UUIDs, any set of unique sentinel
> objects will do.
> 
> -- 
> Greg

There are a number of reasons I'm suggesting UUIDs instead of simple strings:

- Since they are truly unique, and since the hex string doesn't form words in any human language, you can enter the string in your favorite search engine to get more information about the string.  The probability of false positives is almost 0, which is something that a string like 'doc' simply won't give you.

- They don't require any coordination between projects.  That means you don't have to worry that the name you choose for your project conflicts with a name that someone else chooses.  You also don't have to worry about changing the name of your project; UUIDs don't carry any inherent meaning to people so you can keep them even when your project changes.

- They have fixed lengths and formats.  Annotations have been around for a while, which means that any automated tooling is going to have to find a way to deal with a new convention.  If a parser can convert all the keys into UUID instances, then that gives it a high confidence that the code is using this convention.  This is much more difficult to do when the universe of keys is more or less arbitrary.

As for being ugly and error prone, I agree that putting it all in by hand would be horrible.  The code that I wrote demonstrates a different way, which only requires decorators.  It is basically a library that does the following:

    import annotizer
    import uuid

    # Load your uuid in some manner into project_ID.
    project_annotizer = annotizer.annotizer(ID)

    # From now on, you can use project_annotizer's decorators everywhere.

    @project_annotizer.parameter_decorator(a="blah")
    def func(a):
        pass

The example code I've written doesn't use strings, it uses uuid.UUID instances directly, but that is easily changed.  With some work, it can be extended for a large variety of useful annotations, all while hiding the complexities of dealing with UUIDs completely.  

Thanks,
Cem Karan