Improve documentation of attr.ib type parameter

[skewty]

After reading through the documentation it is still unclear to me what the type parameter of attr.ib does. Is it only for type hinting? There is no mention of how it is leveraged by the validator and converter parameters. It seems to be a mystery field with no relationship to any other feature or code.

Given the following code:

import attr

@attr.s
class Foo:
    bar = attr.ib(type=str)

I would expect the following to not be valid: foo = Foo(12)
I also expect the following to not be valid: attr.validate(foo)

Since both are "valid", what value did that type parameter give me?

My expectation would be that when the type= field is provided a default isinstance() validator is applied. Additionally, it wouldn't be a stretch to assume a default converter is applied.

import attr

@attr.s
class Bar:
    x = attr.ib(type=int)

One might expect: bar = Bar('12') to be valid since int('12') is valid.

[hynek]

The docs do say, that it’s equivalent to an PEP 526 type annotation tho. The upcoming version has a whole section on it: http://www.attrs.org/en/latest/types.html

I suppose it would be helpful to link there from the parameter.