#14912: UniqueRepresentation tutorial could use more love
--------------------------------------------+------------------------------
Reporter: darij | Owner:
Type: defect | Status: needs_review
Priority: major | Milestone: sage-5.13
Component: documentation | Resolution:
Keywords: documentation, structure | Merged in:
Authors: Simon King | Reviewers: Darij Grinberg
Report Upstream: N/A | Work issues:
Branch: | Commit:
Dependencies: | Stopgaps:
--------------------------------------------+------------------------------
Changes (by darij):
* cc: tscrim (added)
* reviewer: => Darij Grinberg
* milestone: => sage-5.13
Old description:
> Sadly not my love, unless someone teaches me enough of the stuff that I
> understand it myself.
>
> http://www.sagemath.org/doc/reference/structure/sage/structure/unique_representation.html
>
> One thing I don't understand is:
> {{{
> the preprocessing on the arguments should be idempotent. Namely, If
> MyClass2.__classcall__ calls
> CachedRepresentation.__classcall__(<some_arguments>), then it should
> accept <some_arguments> as its own input, and pass it down unmodified to
> CachedRepresentation.__classcall__().
> }}}
> What is meant by "accept <some_arguments> as its own input"?
>
> Something that possibly should be added is some explanation of the
> difference between {{{__classcall__}}} and {{{__classcall_private__}}}.
> Maybe it doesn't belong there, but then again I have no idea where it
> belongs as it seems not documented at all...
>
> Also there seems to be a typo:
>
> {{{
> The UniqueRepresentation and UniqueFactory classes provide two
> alternative implementations of this design pattern. Both implementations
> have their own merits. UniqueRepresentation is very easy to use: a class
> just needs to derive from it, or make sure some of its super classes
> does. Also, it groups together the class and the factory in a single
> gadget; in the example above, one would want to do:
> }}}
>
> I think it's UniqueFactory, not UniqueRepresentation, which is easy to
> use etc.
>
> __Apply__
>
> [attachment:trac14912-unique_doc.patch]
New description:
Sadly not my love, unless someone teaches me enough of the stuff that I
understand it myself.
http://www.sagemath.org/doc/reference/structure/sage/structure/unique_representation.html
One thing I don't understand is:
{{{
the preprocessing on the arguments should be idempotent. Namely, If
MyClass2.__classcall__ calls
CachedRepresentation.__classcall__(<some_arguments>), then it should
accept <some_arguments> as its own input, and pass it down unmodified to
CachedRepresentation.__classcall__().
}}}
What is meant by "accept <some_arguments> as its own input"?
Something that possibly should be added is some explanation of the
difference between {{{__classcall__}}} and {{{__classcall_private__}}}.
Maybe it doesn't belong there, but then again I have no idea where it
belongs as it seems not documented at all...
Also there seems to be a typo:
{{{
The UniqueRepresentation and UniqueFactory classes provide two alternative
implementations of this design pattern. Both implementations have their
own merits. UniqueRepresentation is very easy to use: a class just needs
to derive from it, or make sure some of its super classes does. Also, it
groups together the class and the factory in a single gadget; in the
example above, one would want to do:
}}}
I think it's UniqueFactory, not UniqueRepresentation, which is easy to use
etc.
Apply:
* [attachment:trac14912-unique_doc.patch]
* [attachment:trac_14912-comments-dg.patch]
--
Comment:
Thanks to Travis's insistence and also his help, I've more or less
reviewed this one at last. The only part I wasn't able to understand is:
{{{
.. NOTE::
For technical reasons, it is needed that ``__classcall__``
respectively
``__classcall_private__`` are "static methods", i.e., they are
callable
objects that do not bind to an instance or class. For example, a
:class:`~sage.misc.cachefunc.cached_function` can be used here,
because it
is callable, but does not bind to an instance or class, because it has
no
``__get__()`` method. A usual Python function, however, has a
``__get__()`` method and would thus under normal circumstances bind to
an
instance or class, and thus the instance or class would be passed to
the
function as the first argument. To prevent a callable object from
being
bound to the instance or class, one can prepend the ``@staticmethod``
decorator to the definition; see :class:`staticmethod`.
}}}
Well, maybe it's just that I have no idea what `__get__` methods do.
for the '''patchbot''':
apply trac14912-unique_doc.patch trac_14912-comments-dg.patch
--
Ticket URL: <http://trac.sagemath.org/ticket/14912#comment:24>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/groups/opt_out.
