help cartesian_product?

[Rolandb]

Hi,

I did not expect parts of the help text; see Class docstring:

Is there a reason for it?

Roland

Type:            LazyImport
String form:     The cartesian_product functorial construction
File:            /opt/sagemath-8.9/local/lib/python2.7/site-packages/sage/misc/lazy_import.pyx
Docstring:      
   A singleton class for the Cartesian product functor.

   EXAMPLES:

      sage: cartesian_product
      The cartesian_product functorial construction

   "cartesian_product" takes a finite collection of sets, and
   constructs the Cartesian product of those sets:

      sage: A = FiniteEnumeratedSet(['a','b','c'])
      sage: B = FiniteEnumeratedSet([1,2])
      sage: C = cartesian_product([A, B]); C
      The Cartesian product of ({'a', 'b', 'c'}, {1, 2})
      sage: C.an_element()
      ('a', 1)
      sage: C.list()         # todo: not implemented
      [['a', 1], ['a', 2], ['b', 1], ['b', 2], ['c', 1], ['c', 2]]

   If those sets are endowed with more structure, say they are monoids
   (hence in the category Monoids()), then the result is automatically
   endowed with its natural monoid structure:

      sage: M = Monoids().example()
      sage: M
      An example of a monoid: the free monoid generated by ('a', 'b', 'c', 'd')
      sage: M.rename('M')
      sage: C = cartesian_product([M, ZZ, QQ])
      sage: C
      The Cartesian product of (M, Integer Ring, Rational Field)
      sage: C.an_element()
      ('abcd', 1, 1/2)
      sage: C.an_element()^2
      ('abcdabcd', 1, 1/4)
      sage: C.category()
      Category of Cartesian products of monoids

      sage: Monoids().CartesianProducts()
      Category of Cartesian products of monoids

   The Cartesian product functor is covariant: if "A" is a subcategory
   of "B", then "A.CartesianProducts()" is a subcategory of
   "B.CartesianProducts()" (see also
   "CovariantFunctorialConstruction"):

      sage: C.categories()
      [Category of Cartesian products of monoids,
       Category of monoids,
       Category of Cartesian products of semigroups,
       Category of semigroups,
       Category of Cartesian products of unital magmas,
       Category of Cartesian products of magmas,
       Category of unital magmas,
       Category of magmas,
       Category of Cartesian products of sets,
       Category of sets, ...]

      [Category of Cartesian products of monoids,
       Category of monoids,
       Category of Cartesian products of semigroups,
       Category of semigroups,
       Category of Cartesian products of magmas,
       Category of unital magmas,
       Category of magmas,
       Category of Cartesian products of sets,
       Category of sets,
       Category of sets with partial maps,
       Category of objects]

   Hence, the role of "Monoids().CartesianProducts()" is solely to
   provide mathematical information and algorithms which are relevant
   to Cartesian product of monoids. For example, it specifies that the
   result is again a monoid, and that its multiplicative unit is the
   Cartesian product of the units of the underlying sets:

      sage: C.one()
      ('', 1, 1)

   Those are implemented in the nested class
   "Monoids.CartesianProducts" of "Monoids(QQ)". This nested class is
   itself a subclass of "CartesianProductsCategory".
Class docstring:
   EXAMPLES:

      sage: from sage.misc.lazy_import import LazyImport
      sage: my_integer = LazyImport('sage.rings.all', 'Integer')
      sage: my_integer(4)
      4
      sage: my_integer('101', base=2)
      5
      sage: my_integer(3/2)
      Traceback (most recent call last):
      ...
      TypeError: no conversion of this rational to integer
Init docstring: 
   EXAMPLES:

      sage: from sage.misc.lazy_import import LazyImport
      sage: my_isprime = LazyImport('sage.all', 'is_prime')
      sage: my_isprime(5)
      True
      sage: my_isprime(55)
      False
Call docstring: 
   Calling self calls the wrapped object.

   EXAMPLES:

      sage: from sage.misc.lazy_import import LazyImport
      sage: my_isprime = LazyImport('sage.all', 'is_prime')
      sage: my_isprime(12)
      False
      sage: my_isprime(13)
      True

[Simon King]

Hi Roland,

On 2019-12-07, Rolandb <roland.va...@gmail.com> wrote:
> I did not expect parts of the help text; see Class docstring:
>
> Is there a reason for it?

What exactly is your question?

Are you asking for the reason why you did not expect parts of the help
text? Only you can answer that question.

Are you asking because you didn't expect some of the *facts* stated in
the help text? Then your question is rather about the behaviour of
cartesian_product than about its help text.

Are you asking because you see a difference between the text shown in
`cartesian_product.__doc__` and `cartesian_product?`? Then, please be
more specific: Are you missing important information in the text shown
by `cartesian_product?`? Are you simply wondering why there is a
difference? Are you asking how to implement documentation for objects
that are somehow wrapped (such as lazy_import, cached_function etc.)

Best regards,
Simon

> Type: LazyImportString form: The cartesian_product functorial constructionFile: /opt/sagemath-8.9/local/lib/python2.7/site-packages/sage/misc/lazy_import.pyxDocstring:

> itself a subclass of "CartesianProductsCategory".Class docstring:

> EXAMPLES:
>
> sage: from sage.misc.lazy_import import LazyImport
> sage: my_integer = LazyImport('sage.rings.all', 'Integer')
> sage: my_integer(4)
> 4
> sage: my_integer('101', base=2)
> 5
> sage: my_integer(3/2)
> Traceback (most recent call last):
> ...

> TypeError: no conversion of this rational to integerInit docstring:

> EXAMPLES:
>
> sage: from sage.misc.lazy_import import LazyImport
> sage: my_isprime = LazyImport('sage.all', 'is_prime')
> sage: my_isprime(5)
> True
> sage: my_isprime(55)

> FalseCall docstring: