#3332: Finalize the Mimeview API changes for 0.10
-----------------------------+----------------------------------------------
Reporter: cboos | Owner: cboos
Type: task | Status: assigned
Priority: high | Milestone: 0.10
Component: general | Version: devel
Severity: blocker | Resolution:
Keywords: mimeview review |
-----------------------------+----------------------------------------------
Changes (by cboos):
* keywords: mimeview => mimeview review
Comment:
I think I have now a quite satisfying refactoring, which is a big leap
ahead from the previous attempts.
The mimeview.api is now a bit more complex, but the IContentConverter
is now simpler and more powerful, and all the code dealing with contents
in the modules is now drastically simplified.
The IHTMLPreviewRenderer interface is deprecated and components
implementing
it are now supported by an adapter implementing the new IContentConverter
interface.
The functionality seems to be OK/improved for the following modules:
attachment, wiki, ticket, query, browser, changeset.
I append here the new mimeview.api module doc, which summarizes
what's to be expected in the new API.
----
The `trac.mimeview` module centralizes the intelligence about typed
content.
Originally, this was about file metadata, principally its MIME type and
eventually the text encoding (charset) used by that content.
Now, this has evolved into managing any kind of typed content,
and deals also with converting a content from one type to another.
A common situation which is now handled part of the general case
is the conversion of any kind of content to a text/html representation.
In order to keep the API of conversion interface IContentConverter simple,
we introduced a few classes, each encapsulating a part of the knowledge
related to the content and the conversion:
* the `ContentType` is used to describe the type of a content.
This is an abstract superclass for:
- `MimeType`, used for storing the mime type string, the charset,
and eventually the name and the commonly used file extension
for that type
- `ObjectType`, used when wrapping an arbitrary Python object
* the `AbstractContent`, which wraps access to the actual content,
and provides a few generic methods, among which `convert()`
is the most important.
- the `ObjectContent`, when the content is an arbitrary Python object
- the `MimeContent` abstract class, which offers an uniform API to
access the data over a wide range of containers:
* the `StringMimeContent`, for handling string content
(like `str`, `unicode` or `Markup` objects)
* the `StructuredMimeContent`, for handling structured content
(like `Element` objects)
* the `LineIteratorMimeContent`, for handling line-oriented string
content (like string iterators or string arrays)
* the `FileMimeContent`, for handling file content
* etc. (as an example, the repository layer defines a
`NodeMimeContent`)
That API provides different ways to get access to the data:
* chunks(), an iterator for reading chunks of raw content
* lines(), an iterator for reading lines from text content
* markup(), when it makes sense to interpret the content as markup
* `__unicode()__`, for converting the content to an `unicode` object
* encode(), for converting the content to a `str` object. Note that
we don't use `__str__` for that on purpose, as we need to be able
to specify the charset.
* size(), for getting a hint about the content size without actually
reading it.
* the `Conversion` class, which is used to specify how a given
`IContentConverter` component will perform a content conversion.
----
This corresponds to attachment:mimeview_api_refactoring-r3612.diff
--
Ticket URL: <http://trac.edgewall.org/ticket/3332#comment:2>
The Trac Project <http://trac.edgewall.com/>
_______________________________________________
Trac-Tickets mailing list
[email protected]
http://lists.edgewall.com/mailman/listinfo/trac-tickets
