refactor: reformat Python code via ruff

[vergenzt]

No description provided.

[nedbat]

Some of the docstrings turned out weird... We can take care of that afterwards I guess.

[vergenzt]

Some of the docstrings turned out weird... We can take care of that afterwards I guess.

Which docstrings do you think are weird? I'm happy to go ahead and update now

[nedbat]

For example: https://github.com/nedbat/cog/pull/33/files#diff-920d9b2896869a64397ed5e32cafcd3087a839fd15e7d5d9480ee5f317b39732L33-R36

In truth, a number of them need to be adjusted to have a good one-line summary first.

[vergenzt]

Using ast-grep (one of my favorite tools lately)...

I'm seeing 63 docstrings in total:

$ sg scan --inline-rules='id: docstrings
           language: python
           rule:
             pattern: >-
               """$DOCSTRING"""
             inside:
               kind: expression_statement
               inside:
                 any:
                 - kind: module
                 - kind: block' --json | jq '.[]' -c | wc -l
63

and 17 docstrings which contain newlines:

$ sg scan --inline-rules='id: docstrings
           language: python
           rule:
             pattern: >-
               """$DOCSTRING"""
             regex: "\n"
             inside:
               kind: expression_statement
               inside:
                 any:
                 - kind: module
                 - kind: block' --json | jq '.[]' -c | wc -l
17

Docstrings with newlines in them:

$ sg scan --inline-rules='id: docstrings
           language: python
           rule:
             pattern: >-
               """$DOCSTRING"""
             regex: "\\n"
             inside:
               kind: expression_statement
               inside:
                 any:
                 - kind: module
                 - kind: block
                   follows:
                     stopBy: end
                     kind: identifier'
help[docstrings]: 
  ┌─ ./cogapp/__init__.py:1:1
  │      
1 │ ╭ ╭ ╭ """Cog content generation tool.
2 │ │ │ │ http://nedbatchelder.com/code/cog
3 │ │ │ │ 
4 │ │ │ │ Copyright 2004-2024, Ned Batchelder.
5 │ │ │ │ """
  │ ╰─│─│───^
  │   │ ╰───'
6 │   │   
7 │   │   from .cogapp import Cog, CogUsageError, main
8 │   │   
  │   ╰──'

help[docstrings]: 
   ┌─ ./cogapp/makefiles.py:25:5
   │      
24 │       def removeFiles(d, basedir="."):
   │           -----------
25 │ ╭ ╭ ╭     """Remove the files created by makeFiles.
26 │ │ │ │     Directories are removed if they are empty.
27 │ │ │ │     """
   │ ╰─│─│───────^
   │   │ ╰───────'
28 │   │       for name, contents in d.items():
   ·   │  
34 │   │               if not os.listdir(child):
35 │   │                   os.rmdir(child)
   │   ╰─────────────────────────────────'

help[docstrings]: 
   ┌─ ./cogapp/whiteutils.py:7:5
   │      
 6 │       def whitePrefix(strings):
   │           -----------
 7 │ ╭ ╭ ╭     """Determine the whitespace prefix common to all non-blank lines
 8 │ │ │ │     in the argument list.
 9 │ │ │ │     """
   │ ╰─│─│───────^
   │   │ ╰───────'
10 │   │       # Remove all blank lines from the list
   ·   │  
29 │   │                   break
30 │   │       return prefix
   │   ╰───────────────────'

help[docstrings]: 
   ┌─ ./cogapp/whiteutils.py:34:5
   │      
33 │       def reindentBlock(lines, newIndent=""):
   │           -------------
34 │ ╭ ╭ ╭     """Take a block of text as a string or list of lines.
35 │ │ │ │     Remove any common whitespace indentation.
36 │ │ │ │     Re-indent using newIndent, and return it as a single string.
37 │ │ │ │     """
   │ ╰─│─│───────^
   │   │ ╰───────'
   · │ │ │
50 │   │           outLines.append(l)
51 │   │       return sep.join(outLines)
   │   ╰───────────────────────────────'

help[docstrings]: 
   ┌─ ./cogapp/utils.py:58:5
   │      
57 │       def change_dir(new_dir):
   │           ----------
58 │ ╭ ╭ ╭     """Change directory, and then change back.
59 │ │ │ │ 
60 │ │ │ │     Use as a context manager, it will return to the original
61 │ │ │ │     directory at the end of the block.
62 │ │ │ │ 
63 │ │ │ │     """
   │ ╰─│─│───────^
   │   │ ╰───────'
   · │ │ │
68 │   │       finally:
69 │   │           os.chdir(old_dir)
   │   ╰───────────────────────────'

help[docstrings]: 
   ┌─ ./cogapp/cogapp.py:93:5
   │      
92 │       class CogUserException(CogError):
   │             ----------------
93 │ ╭ ╭ ╭     """An exception caught when running a user's cog generator.
94 │ │ │ │     The argument is the traceback message to print.
95 │ │ │ │     """
   │ ╰─│─│───────^
   │   │ ╰───────'
96 │   │   
97 │   │       pass
   │   ╰──────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:204:9
    │      
203 │           def error(self, msg="Error raised by cog generator."):
    │               -----
204 │ ╭ ╭ ╭         """The cog.error function.
205 │ │ │ │         Instead of raising standard python errors, cog generators can use
206 │ │ │ │         this function.  It will display the error without a scary Python
207 │ │ │ │         traceback.
208 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
209 │   │           raise CogGeneratedError(msg)
    │   ╰──────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:366:9
    │      
365 │           def createCogModule(self):
    │               ---------------
366 │ ╭ ╭ ╭         """Make a cog "module" object so that imported Python modules
367 │ │ │ │         can say "import cog" and get our state.
368 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
369 │   │           self.cogmodule = types.SimpleNamespace()
370 │   │           self.cogmodule.path = []
    │   ╰──────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:392:9
    │      
391 │           def processFile(self, fIn, fOut, fname=None, globals=None):
    │               -----------
392 │ ╭ ╭ ╭         """Process an input file object to an output file object.
393 │ │ │ │         fIn and fOut can be file objects, or file names.
394 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
395 │   │   
    ·   │  
584 │   │               if fOutToClose:
585 │   │                   fOutToClose.close()
    │   ╰─────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:591:9
    │      
590 │           def suffixLines(self, text):
    │               -----------
591 │ ╭ ╭ ╭         """Add suffixes to the lines in text, if our options desire it.
592 │ │ │ │         text is many lines, as a single string.
593 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
594 │   │           if self.options.sSuffix:
    ·   │  
597 │   │               text = self.reNonEmptyLines.sub(repl, text)
598 │   │           return text
    │   ╰─────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:601:9
    │      
600 │           def processString(self, sInput, fname=None):
    │               -------------
601 │ ╭ ╭ ╭         """Process sInput as the text to cog.
602 │ │ │ │         Return the cogged output as a string.
603 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
604 │   │           fOld = io.StringIO(sInput)
605 │   │           fNew = io.StringIO()
606 │   │           self.processFile(fOld, fNew, fname=fname)
607 │   │           return fNew.getvalue()
    │   ╰────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:739:9
    │      
738 │           def callableMain(self, argv):
    │               ------------
739 │ ╭ ╭ ╭         """All of command-line cog, but in a callable form.
740 │ │ │ │         This is used by main.
741 │ │ │ │         argv is the equivalent of sys.argv.
742 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
    · │ │ │
764 │   │           if self.bCheckFailed:
765 │   │               raise CogCheckFailed("Check failed")
    │   ╰──────────────────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/cogapp.py:793:5
    │      
792 │       def find_cog_source(frame_summary, prologue):
    │           ---------------
793 │ ╭ ╭ ╭     """Find cog source lines in a frame summary list, for printing tracebacks.
794 │ │ │ │ 
795 │ │ │ │     Arguments:
796 │ │ │ │         frame_summary: a list of 4-item tuples, as returned by traceback.extract_tb.
    · │ │ │
801 │ │ │ │ 
802 │ │ │ │     """
    │ ╰─│─│───────^
    │   │ ╰───────'
    · │ │ │
818 │   │                       source = linecache.getline(filename, lineno).strip()
819 │   │           yield filename, lineno, funcname, source
    │   ╰──────────────────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/test_cogapp.py:529:5
    │      
528 │       class FileStructureTests(TestCase):
    │             ------------------
529 │ ╭ ╭ ╭     """Test cases to check that we're properly strict about the structure
530 │ │ │ │     of files.
531 │ │ │ │     """
    │ ╰─│─│───────^
    │   │ ╰───────'
532 │   │   
    ·   │  
658 │   │               """
659 │   │           self.isBad(infile2, "infile.txt(8): Unexpected ']]]'")
    │   ╰────────────────────────────────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/test_cogapp.py:707:5
    │      
706 │       class CogGeneratorGetCodeTests(TestCase):
    │             ------------------------
707 │ ╭ ╭ ╭     """Unit tests against CogGenerator to see if its getCode() method works
708 │ │ │ │     properly.
709 │ │ │ │     """
    │ ╰─│─│───────^
    │   │ ╰───────'
710 │   │   
    ·   │  
770 │   │           self.m("#endif //]]]")
771 │   │           self.assertEqual(self.gen.getCode(), "import cog, sys\n\nprint sys.argv")
    │   ╰───────────────────────────────────────────────────────────────────────────────────'

help[docstrings]: 
    ┌─ ./cogapp/test_cogapp.py:712:9
    │      
711 │           def setUp(self):
    │               -----
712 │ ╭ ╭ ╭         """All tests get a generator to use, and short same-length names for
713 │ │ │ │         the functions we're going to use.
714 │ │ │ │         """
    │ ╰─│─│───────────^
    │   │ ╰───────────'
715 │   │           self.gen = CogGenerator()
716 │   │           self.m = self.gen.parseMarker
717 │   │           self.l = self.gen.parseLine
    │   ╰─────────────────────────────────────'

help[docstrings]: 
     ┌─ ./cogapp/test_cogapp.py:1517:5
     │      
1516 │       class TestCaseWithImports(TestCaseWithTempDir):
     │             -------------------
1517 │ ╭ ╭ ╭     """When running tests which import modules, the sys.modules list
1518 │ │ │ │     leaks from one test to the next.  This test case class scrubs
1519 │ │ │ │     the list after each run to keep the tests isolated from each other.
1520 │ │ │ │     """
     │ ╰─│─│───────^
     │   │ ╰───────'
     · │ │ │
1531 │   │               del sys.modules[modname]
1532 │   │           super().tearDown()
     │   ╰────────────────────────────'

(edited to reference the identifier too so it shows up in CLI output)

I don't think any of these look awful, personally. 🤷 Not sure they're a priority if it were up to me.

Up to you though. Any changes you wanna make?

[nedbat]

Don't worry about the docstrings, we can do it later.

[nedbat]

I'll have to fix the CI for the MacOS changes GitHub made recently. That will require rebasing, which will change the commit id for the blame-ignore file.... The fun never ends.

[vergenzt]

I think you can push an empty commit? Via git commit --allow-empty -m "retrigger ci" or something like that

[vergenzt]

Either way - however you want to do it 😅

[nedbat]

In this case an empty commit won't help because the actions will be run as they are on your branch. You'll need to rebase to get the CI changes I'll make (soon).

[nedbat]

The main branch has the updated CI workflow.

[vergenzt]

Alright I've rebased and changed the SHA in .git-blame-ignore-revs. However when I try to view blame for cogapp.py from my branch I get an error message that "Your .git-blame-ignore-revs file is invalid".

Could that just be because the SHA hasn't been merged to the default branch yet?

[nedbat]

I don't know the weirdness about how the file is being used, but we can fix it later.

[nedbat]

The commit changed during the rebase, but also there was an invisible character in the middle of the hash. ¯_(ツ)_/¯

I fixed it up on main anyway.

[vergenzt]

Got it. I hadn't realized you'd be rebasing the changes onto main instead of merging. I'll leave out the .git-blame-ignore-revs change for #34