rob-smallshire / cartouche Goto Github PK

Original author: [email protected] (October 05, 2012 16:47:07)

What steps will reproduce the problem?

1. Write a comment that does not parse correctly, like leaving the colon (:) out of an Args specification.

What is the expected output? What do you see instead?

I expect cartouche to let me know what file / line number (maybe line contents) that parsed incorrectly. I could probably figure it out from there.

Instead it fails with this error:
"Invalid cartouche argument syntax"

There are a lot of files in the project, and lots of comments with Args lists, where do I start?

What version of the product are you using? On what operating system?

cartouche 0.9 from PyPI on CentOS 6 64 bit

Original issue: http://code.google.com/p/cartouche/issues/detail?id=9

It would be nice to have an official version with the latest code on pypi.python.org

Original author: [email protected] (June 29, 2012 07:02:29)

Class docstring should have, according to the Google Python Style guide an Attributes: section for public attributes.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=5

Original author: austin.bingham (June 26, 2012 18:25:42)

With a docstring like this:

def foo():
'''Something.

Args:
  * arg1: an argument
'''

hieroglyph will throw an exception.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=1

cartouche/nodes.py is invalid Python 2.X syntax because print is being used like a function instead of a statement which does not allow keyword args.

  File "/home/sgoss/projects/cartouche/cartouche/nodes.py", line 64
    print("Missing argument description for {name}".format(name=self.name), file=sys.stderr)
                                                                                ^
SyntaxError: invalid syntax

Original author: [email protected] (June 29, 2012 07:01:08)

Imported from hieroglyph

The following docstring:

'''
Execute the command described by concatenating the string function arguments
with the p4 -s global scripting flag and return the results in a dictionary.

For example, to run the command::

  p4 -s fstat -T depotFile foo.h

call::

  p4('fstat', '-T', 'depotFile', 'foo.h')

Args:
    args: The arguments to the p4 command as a list of objects which will
        be converted to strings.

Returns:
    A dictionary of lists where each key in the dictionary is the field name
    from the command output, and each value is a list of output lines in
    order.

Raises:
    PerforceError: If the command could not be run or if the command
        reported an error.
'''

produced the error:

lines = [u'Execute the command described by concatenating the string function ar
guments', u'with the p4 -s global scripting flag and return the results in a dic
tionary.', u'', u'For example, to run the command,', u'', u' p4 -s fstat -T dep
otFile foo.h', u' ', u'call,', u'', u" p4('fstat', '-T', 'depotFile', 'foo.h')
", u'', u'Args:', u' *args: The arguments to the p4 command as a list of obje
cts which will', u' be converted to strings.', u' ', u'Returns:', u'
A dictionary of lists where each key in the dictionary is the field name', u'
from the command output, and each value is a list of output lines in', u'
order.', u' ', u'Raises:', u' PerforceError: If the command could not be r
un or if the command', u' reported an error.', u'']

Exception occurred:
File "c:\Python27\lib\site-packages\hieroglyph-0.5dev_20110318-py2.7.egg\hiero
glyph\hieroglyph.py", line 80, in convert_args
last_child = arg.children[-1] if len(arg.children) != 0 else arg
UnboundLocalError: local variable 'arg' referenced before assignment

Original issue: http://code.google.com/p/cartouche/issues/detail?id=4

Original author: [email protected] (June 29, 2012 06:59:40)

Issue imported from hieroglyph

Running Sphinx v1.0.7
loading pickled environment... not yet created
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [ 16%] api/canoncial
lines = [u'Parse a single line of a tree to determine depth and node.', u'', u'A
rgs:', u' A single line string from a SCons dependency tree.', u' ', u'Ret
urns:', u' A 2-tuple containing the tree 0 based tree depth as the first', u'
element and the node description as the second element.', u'', u'Raises:', u
' ValueError: If line does not have the expected form.', u'']

Exception occurred:
File "c:\Python27\lib\site-packages\hieroglyph-0.5dev_20110318-py2.7.egg\hiero
glyph\hieroglyph.py", line 80, in convert_args
last_child = arg.children[-1] if len(arg.children) != 0 else arg
UnboundLocalError: local variable 'arg' referenced before assignment
The full traceback has been saved in c:\users\robert~1.emr\appdata\local\temp\sp
hinx-err-2ngbwq.log, if you want to report the issue to the developers.

In this case the fourth element contains u' A single line string from a SCons dependency tree.' whereas it should contain u' line: A single line string from a SCons dependency tree.'

Hieroglyph should detect this and report a sensible error message.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=3

Original author: [email protected] (October 05, 2012 18:28:36)

What steps will reproduce the problem?

1. pip install cartouche or in source folder python setup.py install before sphinx is installed

What is the expected output? What do you see instead?

I expect the sphinx requirement to be resolved automatically, instead it just explodes because setup.py tries to import sphinx when it is importing the version number from the code.

Please provide any additional information below.

This line is the problem:

from cartouche import __version__ as version

You can't do that. if you replace it with this line:

version = 0.9

it works! it gives pip a chance to resolve the sphinx requirement automatically.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=10

This fragment reproduces the problem:

        Raises:
            ValueError: If the ``right_hand_side`` does not have a compatible
                shape.

        Usage:
            effective_porosity = total_porority * ffi

Original author: [email protected] (October 05, 2012 16:34:40)

What steps will reproduce the problem?

1. Create an args list like this:
   Args:
   foo (foo_module.SomeClass): something something
2. Let cartouche loose on the code

What is the expected output? What do you see instead?

It is expected that cartouche could parse the "foo_module.SomeClass" bit, since you know, there might be a bar_module.SomeClass also in play, we want to specify which one we are using.

Instead, cartouche spits out this error without any hint of what file or line might be causing the problem: "Invalid cartouche argument syntax"

What version of the product are you using? On what operating system?

cartouche 0.9 from PyPI, CentOS 6 64 bit

Please provide any additional information below.

it's obvious that this regex is insufficient:

ARG_REGEX = re.compile(r'({0,2}\w+)(\s+((\w+)))?\s_:\s_(.)')

trying to match the class specifier with \w+

Original issue: http://code.google.com/p/cartouche/issues/detail?id=8

Original author: [email protected] (October 17, 2012 19:47:13)

What steps will reproduce the problem?

1. Include the following as the docstring for a method:
   """
   Raises:
   Exception: This is a multi-line
   bug.
   """
2. Try to build the documentation with sphinx-build

What is the expected output? What do you see instead?

Expected:
build without errors.

Actual:
Extension error:
Invalid cartouche exception syntax

What version of the product are you using? On what operating system?

Sphinx v1.1.3
cartouche v0.9
CentOS release 6.3 (Final)

Please provide any additional information below.

n/a

Original issue: http://code.google.com/p/cartouche/issues/detail?id=11

I think nose runs the setup function in sphinxext.py erroneously (mistaking it as a test setup function), causing it to explode before any actual tests are run:

$ nosetests cartouche.test
E
======================================================================
ERROR: test suite for <module 'cartouche.test' from '/home/sgoss/projects/cartouche/cartouche/test/__init__.pyc'>
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/sgoss/projects/cartouche_env/local/lib/python2.7/site-packages/nose/suite.py", line 208, in run
    self.setUp()
  File "/home/sgoss/projects/cartouche_env/local/lib/python2.7/site-packages/nose/suite.py", line 291, in setUp
    self.setupContext(ancestor)
  File "/home/sgoss/projects/cartouche_env/local/lib/python2.7/site-packages/nose/suite.py", line 314, in setupContext
    try_run(context, names)
  File "/home/sgoss/projects/cartouche_env/local/lib/python2.7/site-packages/nose/util.py", line 476, in try_run
    return func(obj)
  File "/home/sgoss/projects/cartouche/cartouche/sphinxext.py", line 6, in setup
    app.add_config_value('cartouche_accept_bulleted_args', False, 'env')
AttributeError: 'module' object has no attribute 'add_config_value'

----------------------------------------------------------------------
Ran 0 tests in 0.000s

FAILED (errors=1)

Original author: austin.bingham (June 27, 2012 07:08:05)

A docstring with a dotted exception name causes an invalid syntax exception. For example:

'''
A docstring.

Args:
arg1: Some argument

Returns: Some kind of value.

Raises:
exceptions.SomeError: There was some error.
'''

Original issue: http://code.google.com/p/cartouche/issues/detail?id=2

Original author: [email protected] (August 10, 2012 14:17:06)

Support a Usage: block allowing the user to provide a simple code example.

For example,

Usage:

 foo = my_method(7)

which will be formatted as 'code'

Original issue: http://code.google.com/p/cartouche/issues/detail?id=7

Original author: [email protected] (June 29, 2012 07:04:57)

Defect migrated from hieroglyph to cartouche.

It would be really useful if the offending line was also included in the error message.
Then debugging would be simpler.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=6