manuel plugin for Martian's FakeModule?

[Martijn Faassen-2]

Hi there,

I'm just throwing this idea out there in the hopes someone will want to
hack on it.

With Martian we've introduced a FakeModule facility to make it easier to
test whole python modules from within doctests. See the Martian docs for
examples:

http://pypi.python.org/pypi/martian/0.12

This still looks fairly ugly, all this stuff:

   >>> blahblah
   ... blah
   ... blahblah

Manuel is a library that makes it easier to write testable documentation
(and documented tests):

http://packages.python.org/manuel/

It includes a number of plug-ins to support all sorts of nice features
that you don't get in plain doctests.

It looks to me like the FakeModule bit could make a very nice Manuel
extension.

The FakeModule support + manuel integration could be in a separate
library, but since this seems to be of general utility better yet it
seems to me would be integrating this into Manuel proper.

I hope an interested hacker wants to work on this!

Now some other ideas that shouldn't discourage an interested hacker from
taking up the previously sketched out project - others could do what's
followed, step by step:

Once this is done, the next step would be for people to adjust the
Martian doctests to use this facility. They could look a lot prettier
and more readable.

Finally, a step where we can hopefully recruit a whole bunch of
volunteers would be to use this technology for all the tests we have in
grokcore.* and grok. Right now we use the approach where the doctest is
on the top of the real module, with some fixtures on the side. It'd be
prettier if we could just make a bunch of documents instead that include
these modules. I imagine with some test-isolation support (we probably
need to extend the Manuel stuff to roll back configuration too), we
could have a whole bunch of related tests in a single document, with
more explanatory text.

Regards,

Martijn

_______________________________________________
Grok-dev mailing list
Grok-dev@...
https://mail.zope.org/mailman/listinfo/grok-dev

[PAW]

Hi,

2009/10/7 Martijn Faassen <faassen@...>:
> It looks to me like the FakeModule bit could make a very nice Manuel
> extension.
>
> The FakeModule support + manuel integration could be in a separate
> library, but since this seems to be of general utility better yet it
> seems to me would be integrating this into Manuel proper.
>
> I hope an interested hacker wants to work on this!

I've written some code and tests in an attempt to interpret what
you're meaning here. Perhaps it could form the basis of a solution.
The tests pass from within the manuel package but I haven't actually
tried it in a doc test yet (need time!!!). I've gone ahead and used
the format:

 .. module-block:: module_name
      import xyz

      class ABC: pass

Let me know if I'm close to the mark, and I'll branch manuel or something.

Hope this gets the ball rolling...

Thanks,
Paul

manuel.fake_modules
===================

This document discusses the fake_module plugin for manuel that allows
doctests to define and then use modules.

   >>> import manuel
   >>> import manuel.fake_module

   >>> source = """\
   ... This is a module doc-test:
   ...
   ... .. module-block:: fake_module
   ...      import whatever
   ...      class Something:
   ...         pass
   ...
   ... As you can see, it does much!!
   ... """
   
   >>> doc = manuel.Document(source)
   >>> manuel.fake_module.find_fakes(doc)

Let's extract the module name and its source:

   >>> for region in doc:
   ...    if region.parsed:
   ...       print region.parsed.module_name
   ...       print region.source
   fake_module
   .. module-block:: fake_module
        import whatever
        class Something:
           pass
   <BLANKLINE>
   <BLANKLINE>

The code can correctly parse multiple modules:

   >>> source = """\
   ... Our system has a few modules:
   ...
   ... .. module-block:: some_module
   ...      class Foo:
   ...         pass
   ...
   ... and:
   ...
   ... .. module-block:: an_other_module
   ...      class Bar:
   ...          pass
   ...
   ... fin
   ... """

   >>> doc = manuel.Document(source)
   >>> manuel.fake_module.find_fakes(doc)
   
Again, we extract the various parsed regions:

   >>> for region in doc:
   ...     if region.parsed:
   ...         print region.parsed.module_name
   ...         print region.source
   some_module
   .. module-block:: some_module
        class Foo:
           pass
   <BLANKLINE>
   <BLANKLINE>
   an_other_module
   .. module-block:: an_other_module
        class Bar:
            pass
   <BLANKLINE>
   <BLANKLINE>

Let's execute these regions into a globs dictionary of our own:

  >>> glob = {}
  >>> for region in doc:
  ...     if region.parsed:
  ...         manuel.fake_module.execute_into_module(
  ...                            region, doc, glob)

Let's check that our glob contains the modules with their names:

  >>> for name, module in glob.iteritems():
  ...     print module.__name__, ":", type(module)
  manueltest.fake.some_module : <type 'module'>
  manueltest.fake.an_other_module : <type 'module'>

Let's also confirm that the modules contain their respective class
definitions:

  >>> for name, module in glob.iteritems():
  ...     print dir(module)
  ['Foo', '__builtins__', '__doc__', '__file__', '__name__']
  ['Bar', '__builtins__', '__doc__', '__file__', '__name__']

We would also want to ensure that we can import the module correctly
too. The fake_module system also adds the modules under their own
namespace 'manueltest.fake', as you can see from the previous tests:

  >>> import manueltest.fake.some_module
  >>> import manueltest.fake.an_other_module
  >>> manueltest.fake.some_module.Foo
  <class manueltest.fake.some_module.Foo at ...>
  >>> manueltest.fake.an_other_module.Bar
  <class manueltest.fake.an_other_module.Bar at ...>

Note: There is no checking done to ensure that the module definition
hasn't overridden any previous modules defined in the doctest.


_______________________________________________
Grok-dev mailing list
Grok-dev@...
https://mail.zope.org/mailman/listinfo/grok-dev

[Leonardo Rochael Almeida]

Hi Paul,

That's really impressive, I'd say it's much better to type a whole
module like this than in a standard doctest. Reindenting code is much
easier than adding ">>> " to it. And to top it off no need to bother
with the weird looking class faking as module thing.

My next question was going to be why didn't you reuse any of the
Martian code for fake modules, but by looking at your code it seems
there wasn't much to reuse anyway, right?

Good job!

On Thu, Oct 22, 2009 at 13:35, Paul Wilson <paulalexwilson@...> wrote:

> Hi,
>
> 2009/10/7 Martijn Faassen <faassen@...>:
>> It looks to me like the FakeModule bit could make a very nice Manuel
>> extension.
>>
>> The FakeModule support + manuel integration could be in a separate
>> library, but since this seems to be of general utility better yet it
>> seems to me would be integrating this into Manuel proper.
>>
>> I hope an interested hacker wants to work on this!
>
> I've written some code and tests in an attempt to interpret what
> you're meaning here. Perhaps it could form the basis of a solution.
> The tests pass from within the manuel package but I haven't actually
> tried it in a doc test yet (need time!!!). I've gone ahead and used
> the format:
>
>  .. module-block:: module_name
>      import xyz
>
>      class ABC: pass
>
> Let me know if I'm close to the mark, and I'll branch manuel or something.
>
> Hope this gets the ball rolling...
>
> Thanks,
> Paul
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> https://mail.zope.org/mailman/listinfo/grok-dev
>
>

_______________________________________________
Grok-dev mailing list
Grok-dev@...
https://mail.zope.org/mailman/listinfo/grok-dev

[PAW]

2009/10/22 Leonardo Rochael Almeida <leorochael@...>:
> That's really impressive, I'd say it's much better to type a whole
> module like this than in a standard doctest. Reindenting code is much
> easier than adding ">>> " to it. And to top it off no need to bother
> with the weird looking class faking as module thing.

Absolutely!

> My next question was going to be why didn't you reuse any of the
> Martian code for fake modules, but by looking at your code it seems
> there wasn't much to reuse anyway, right?

If by 'reuse' you mean directly reuse (via import), then I think this
is intended to be a separate standalone replacement for the
fake_import and FakeModule stuff.

If you mean reuse the code/logic, then I have actually used quite a
bit of fake_import. However, currently I don't know how 'exec' in
'dict' handles the exec'd code's context. If it's smart enough to set
all the function objects up with the correct __module__ values etc,
then I don't think we need to use much more of what's in fake_import.
I'll know when I write more tests.

Hope that answers your question.
Thanks
Paul
_______________________________________________
Grok-dev mailing list
Grok-dev@...
https://mail.zope.org/mailman/listinfo/grok-dev

[PAW]

> 2009/10/7 Martijn Faassen <faassen@...>:
>> It looks to me like the FakeModule bit could make a very nice Manuel
>> extension.
>>
>> I hope an interested hacker wants to work on this!
>
> [SNIP]
>
> Let me know if I'm close to the mark, and I'll branch manuel or something.

Some preliminary ideas can be found at:

http://svn.zope.org/manuel/branches/pwilson-try-fake-modules/

Regards,
Paul
_______________________________________________
Grok-dev mailing list
Grok-dev@...
https://mail.zope.org/mailman/listinfo/grok-dev