Bad type in get_or_create docs

[eranzim]

I believe there is a mistake in the docs of get_or_create class method in core.py. They say:

        :param props: dict of properties to get or create the entities with.
        :type props: tuple

Passing a tuple results in an error (AttributeError: 'tuple' object has no attribute 'get')... I believe it should be dict, like the description says.
Being as it is, PyCharm falsely alerts me I'm passing a wrong type in all my get_or_create calls.
Thanks!

[leonaidus]

@eranzim This representation is correct as it takes tuple of dictionaries.
To understand this fact try below code -

def myfunc(*props):
    return type(props)

print(myfunc({'name': 'Leonaidus'}))

This gives us

<class 'tuple'>

which is python behaviour for Non-Keyword Arguments

[eranzim]

I understand, and this makes sense that args would be a tuple inside the function. Does that mean that there is a bug in PyCharm? Because even in the example you gave, it will issue a warning if I add :type props: tuple in the docs, but not if I add :type props: dict.. It makes sense to me that since args will always be a tuple inside the function, the type specification in the docstring probably refers to the elements inside the tuple. My opinion is reinforced when I pass multiple dicts to myfunc. With :type props: dict there is no warning, but with :type props: tuple PyCharm marks each dict separately (rather than just the whole argument list) and issues a type mismatch warning.

[aanastasiou]

@eranzim Thanks, it is worth the clarification. Yes, the type right there would be tuple and equivalent to a call to a dict like params.items().

[aanastasiou]

@eranzim This has now been changed to:

        :param props: Arguments to get_or_create as tuple of dict with property names and values to get or create 
                      the entities with.
        :type props: tuple

Not sure about what PyCharm uses for code analysis and whether this should be looked any further though.

[dixanms]

As Python always packages function arguments as a tuple when function uses *some_name to declare an undetermined number arguments, the convention seems to be to use any documented type (docstring :type) as the type of tuple's contained elements.

PEP 484 suggests that

I reached out to JetBrains regarding this and this is their response:

"one is not really expected to annotate arbitrary (*args) or default (**kwargs) arguments as tuples or dicts. As you said they are always tuples or dicts so the static analysis tools (or engineers reading the code) always know the collection type.

The part of interest is the tuple/dict items type. See a relevant part of PEP 484 https://www.python.org/dev/peps/pep-0484/#arbitrary-argument-lists-and-default-argument-values I guess we can extrapolate the same logic to type annotations in docstrings."

Accordingly, what makes sense is to change get_or_create and create_or_update methods to

  :type props: dict