Add parse_as_type function

[dmontagu]

Change Summary

Adds just the parse_as_type function from #812, along with some documentation.

The documentation may need some work; @samuelcolvin if you give me some direction on what you'd like I'd be happy to modify it. I also think it may make sense to flesh it out a little more
and/or place it on a separate "tools" page once the dump_as_type functionality is implemented.

Related issue number

Addresses minor parts of #811, but to close that issue the dump_as_type functionality will be more important.

Given the lengthy back and forth on #812 I figured it might make more sense to just start fresh and break the pull request into smaller chunks.

Checklist

• Unit tests for the changes exist
• Tests pass on CI and coverage remains at 100%
• Documentation reflects the changes where applicable
• changes/<pull request or issue id>-<github username>.md file added describing change
  (see changes/README.md for details)

[codecov]

Codecov Report

Merging #934 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff          @@
##           master   #934   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          19     20    +1     
  Lines        3293   3317   +24     
  Branches      651    653    +2     
=====================================
+ Hits         3293   3317   +24

Impacted Files	Coverage Δ
pydantic/tools.py	100% <100%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 62bc930...315395b. Read the comment docs.

[aldanor]

This doesn't seem to work with dataclasses, is it supposed to?

[dmontagu]

It should work if and only if you could put dataclasses as fields on a pydantic model.

I don't know whether @samuelcolvin would want to support that or not.

[samuelcolvin]

Not not sure about obj I think it could be confusing, I think we should use custom root types, e.g. __root__.

That might involve fixing #908 but I think that's a good idea anyway.

[ahirner]

Is this a partial solution for #481 and what is missing?

[dmontagu]

Is this a partial solution for #481 and what is missing?

This is orthogonal to the points raised in that issue, but I think it would be nice if it could support pydantic dataclasses too. I'm not sure how I'd make that happen though. I think if you added the functionality discussed in that issue, it would probably make it easier to have the parse_as_type function handle pydantic dataclasses.

Edit: Actually, it's not quite orthogonal, but it goes beyond what is discussed in that issue -- it supports parsing any type parseable by pydantic, not just models / dataclasses.

[ahirner]

i like the tests, especially test_parse_as_type_preserves_subclasses and think it would be no problem to add functionality to achieve the same with dataclasses.
so correct me if I'm wrong: parse_as_type(obj, dataclass_or_model_type) == parse_obj(dataclass_or_model_type, obj) ?

edit: clarified input to mean types

[dmontagu]

so correct me if I'm wrong: parse_as_type(obj, dataclass_or_model_type) == parse_obj(dataclass_or_model_type, obj) ?

Yeah, I ordered arguments based on what seemed intuitive to me from the function name parse_as_type -> parse obj as type type_), but I am happy to reverse if preferable. The other order would be more consistent with typing.cast, so maybe that's better.

[dmontagu]

Just waiting on #958 to replace obj with __root__.

[dmontagu]

@ahirner Actually, to my surprise, it looks like this works out of the box with dataclasses. (I added a test.)

This will also handle the parse_file function.

I might hold off on implementing the to_json() function because we'll want to add dump_as_type from #811, and that may affect the best way to implement the to_json function. On the other hand, there should be a to_json function that doesn't depend on the type you are dumping, so maybe it's fine to add now.

[samuelcolvin]

otherwise looks good.

[samuelcolvin]

otherwise LGTM.

[samuelcolvin]

I'm still not sure about parse_obj as a name, I understand why you chose it but:

1. It's not really that similar to BaseModel.parse_obj()
2. If you're new to pydantic it's less understandable than parse_as_typeor whatever

I guess I'd prefer parse_as_type() and parse_file_as_type(). (Or maybe better parse_object_as() and parse_file_as()). Thoughts?

[dmontagu]

I'm fine with that; it seemed similar to me since it is basically like the unbound version of the BaseModel.parse_obj classmethod (that doesn't need to have a BaseModel passed as the first argument). But I have no qualms with using different names.

I'd be in favor of parse_object_as and parse_file_as. I can change it to that if you confirm that's what you want. (If you want to think about it a little longer that's fine too.)

[samuelcolvin]

Sorry to be indecisive. Let's go with parse_object_as and parse_file_as.

[dmontagu]

@samuelcolvin I did the renames and added some docs; assuming you have no issues with the docs, I think this is just waiting now on changing obj to __root__, which requires #958.

(To be clear, I'm fine with this whether we use __root__ or obj though; I don't know if there is a performance implication to using a custom root model for this, but I'm guessing not?.)