-
Notifications
You must be signed in to change notification settings - Fork 49
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Big refactoring of the model and astbuilder #430
Comments
If I understand correctly:
The advantages we're looking for would include:
DocspecWhile Docspec intents to support languages other than Python in the future, I don't think that we have that ambition for Having a mode in which I think the default mode would still be Docspec support might be useful for Python bindings, where API docs from the original language could be mixed into the Python API docs. There is pretty much a 1:1 correspondence between the Docspec format and the ParserIn
There are also some disadvantages:
The I don't think documentation comments are a strong enough reason for us to switch parsers. If a project wants to use documentation comments instead of inline docstrings, they could use a different tool to produce a Docspec file and then feed that Docspec file as input to Maybe
|
Yes, yes, yes, yes. And also,
I agree
I've fixed it, please tell me it's ok.
I went with subclassing because I want the new objects to be compatible with the standard one. And I think it should stay compatible, whether it's with subclassing or with another model that repeats the same attributes plus new ones, it's ok. But you are right that putting the analysis code inside the dataclasses is not best practice, so I'll try to avoid that by doing more of the job in the loader/astbuilder. I don't think pydocspec should care about the docstring format and fields. I think the scope of pydocspec is the python language analysis. And since docstring are not part of any clear PEP, I'de suggest we leave that for the client libraries.
I'm 100% open to this and I encourage it, if you have a simple protocol that you'de want to share (simpler that twisted's, or vulgarized), that could help us. I would be very happy.
Yes, let's avoid that. The first part of the refactor could be the externalization of the astbuilder in the |
I think having a mapping with preferred public names of reparented objects and trying to move around objects at the rendering time would be cumberstone. I think the reparenting should be part of our model in some fashion. If we want to talk about some smaller adjustments, in our current model, we could create a new It could have the following interface: class ExportedName(Documentable):
kind = DocumentableKind.EXPORTED_NAME
locations: List[Documentable]
# The first re-export could be the real object, other re-exports could be aliases to the real object. This way, the renderer can document both the implementation location of a re-exported object (maybe as private API) and the exported locations of an object in its implementation page.
Or perform the resolution in a model where reparenting is not a thing. Or add a new attribute :
The Anyway, I'm probably missing some issues. Tell me what you think. |
Regarding on-demand processing, I understand that the core of the fields should be initialized right from the instantiation of the objects, like AST properties, some other attributes are really simple to determine from informations that already are in the tree. I used the cached properties when I thought would be appropriate. For instance the |
To answer this specific question, my opinion is that, since we are opting for a Regarding the the Regarding the instantiation of the model attributes (like |
Here is what I'm proposing in order to separate it in several steps and make this the most modular as possible:
|
Before doing that, the Twisted deprecation handling should be integrated into pydoctor (#315). We need to adopt a design that allow generic extra informations to be added to objects. Deprecation shouldn't need a special renderer in the templates, it should only leverage a generic mechanism, such that implementation is not coupled with rendering anymore. |
I’ve thought about it a while and I think that totally externalize our ast builder into another package is not a great idea. I believe the best way forward is to adjust our own model classes such that they are closer to the docspec classes until the point where it’s easy to write a encoder and a decoder Documentable <-> Docspec. I don’t think we should use pydocspec, actually. But it was good to build the project to have a better understanding of the ast builder and the astroid inference system. Basically, I think everything should happend with our own model classes. So I’ll close this issue. I’ll create follow up issue for specific stuff to do. Like make the Documentable classes compatible with docspec. |
Hello,
I'm working on a huge refactoring of the model and the AST builder.
I've roughly proposed the changes here #295 (comment), I'll try to go in more details here, and hopefully get a consensus around this and move forward.
The core of my proposition is the following:
Documentable
), becausepydocspec
will not reparent objets when visiting import statements, it simply creates a specialIndirection
object (instead of using a dict to keep track of imports). Object that can later be followed by theApiObject.resolve_name()
method. (Note that I've basically adapted allDocumentable
features related to python language processing topydocspec
)Documentable
objects from that, improve the re-exporting system and create a new class doing the bridge between thepydocspec
word and theDocumentable
word. Let's call itDocumentableLookup
and it would be aSystem
attribute (for the other way arround, simplyDocumentable.spec:pydocspec.ApiObject
shoud be ok). It would have to be created at the time of the conversionpydocspec
->Documentable
, could have the following interface:(we can probbly adapt the code of the
ReverseMap
to fit our needs.)Documentable.resolveName()
such that the lookup happens in thepydocspec
word, but be translated in theDocumentable
word before returning the result.What are the motivations for such a massive change?:
pydocspec
do not handle duplicates explicitly. Instead it stores the members in a list (not a dict, so multiple members can have the same name) and theApiObjectsRoot
class (equivalent of theSystem
class) stores all objects in a mapping that do not discard older objects when they get overriden (see DuplicateSafeDict). I don't say fixing this issue is simple, probably the name resolution will be partially broken anyway (returning only the first result, leaving a warning for instance), but we could do something better than renaming.Design and logistics:
pydocspec
, it's sill in a state where it's not really helpful yet (we can only convert regular docspec trees, but that's expensive on ast).pydocspec
is still version 0.0.0 so anything can be changed.pydocspec
totwisted
org if you feel like this could work.The text was updated successfully, but these errors were encountered: