search

knorrie / python-btrfs

Python Btrfs module
GNU Lesser General Public License v3.0
112 stars 22 forks source link

ctree.py:543: SyntaxWarning: invalid escape sequence '\_' #46

Closed hhoffstaette closed 6 months ago

hhoffstaette commented 6 months ago

I just noticed the following warning while bumping the Gentoo package to v14 using python-3.12:

/usr/lib/python3.12/site-packages/btrfs/ctree.py:543: SyntaxWarning: invalid escape sequence '\_'

The actual line is here but I'm not sure what to do about this in a portable manner (across Python versions) or exactly how the pydoc comments are supposed to work.

hhoffstaette commented 6 months ago

Ah..the trailing underscore is necessary because type is a reserved keyword. How unfortunate. Also as far as I can tell the doc is wrong to begin with, as the actual property is called _type, not type_ :zany_face:

knorrie commented 6 months ago

Ah, thanks, I also see it when using Python 3.12.

I just pushed a fix to the develop branch.

The documentation is about the type_ parameter when constructing an object:

key1 = btrfs.ctree.Key(425, 'DIR_ITEM', 17818406)

vs

key1 = btrfs.ctree.Key(objectid=425, type_='DIR_ITEM', offset=17818406)

Library users probably never have to use it in this explicit way. Appending the underscore is a usual way to fix keyword conflicts.

The property _type also exists, but it's not part of the public api and not part of the documentation. Users can actually use .type which is the setter/getter wrapper for _type. :D

hhoffstaette commented 6 months ago

That was quick, thank you! I know it is "just a warning" and has been there since at least v13, but still. I was just trying to untangle the type_ vs. _type thing and came to the same conclusion re. public vs. private API. Apparently simply removing the '\' also works, but who knows what other wheel will come off then. ¯\(ツ)/¯