Metadata-Version: 2.1
Name: coblack
Version: 0.2
Summary: Black-compliant formatter/rewrapper for Python comments.
Home-page: https://github.com/tfiers/coblack
Author: Tomas Fiers
Author-email: tomas.fiers@gmail.com
License: UNKNOWN
Project-URL: Source Code, https://github.com/tfiers/coblack
Description: # CoBlack
        
        _CoBlack_ is a <em><a href="https://black.readthedocs.io">Black</a></em>-compliant formatter/rewrapper for Python comments.
        
        
        #### Example code
        
        Before:
        ```python
        def care_for(self, favorite_plant):
            self.sing_a_lullaby_to(favorite_plant)  # This should help them grow. Note that this comment is too long to fit on one line, given the recommended line length.
            favorite_plant.water(100 * mL)  # Prevent dehydration.
        ```
        
        After:
        ```python
        def care_for(self, favorite_plant):
            self.sing_a_lullaby_to(favorite_plant)  # This should help them grow. Note that this
            #                                       # comment is too long to fit on one line,
            #                                       # given the recommended line length.
            favorite_plant.water(100 * mL)  # Prevent dehydration.
        ```
        The extra `#`'s at the beginning of each line are necessary to be Black-compliant:\
        If they were not there, Black would pull the comments to the start of the line, 
        destroying the alignment, and making the code look messier.
        (Compare to how the [naive way](#naive-way-of-wrapping-comments) of wrapping comments looks).
        
        
        <br>
        
        
        ## Installation
        
        ```
        $ pip install coblack
        ```
        
        This will get you the [![latest release on PyPI](https://img.shields.io/pypi/v/coblack.svg?label=latest%20release%20on%20PyPI:)](https://pypi.python.org/pypi/coblack/)
        
        (Upgrade an existing installation of _CoBlack_ by adding the `--upgrade`/`-U` flag).
        
        
        <br>
        
        
        ## Usage
        
        In your terminal:
        ```
        $ coblack my_file.py
        ```
        This wraps & fills out multiline comments, and passes the result through `black`.\
        The file is edited in-place.
        
        Get info on additional options (such as eg `-l` to set the line length) 
        with `coblack -h`.
        
        
        <br>
        
        
        ## IDE integration
        
        For PyCharm, create a new [_External Tool_](https://www.jetbrains.com/help/pycharm/configuring-third-party-tools.html),
        as follows:
        
        <img alt='Screenshot of External Tool UI in PyCharm. Gist: `coblack "$FilePath$"`'
             src='doc/IDE_integration_PyCharm.png'
             width=600>
        
        Then assign a keyboard shortcut to this tool.\
        This enables you to format your files quickly and often during coding sessions.
        
        In VS Code, you'd create a new [_Task_](https://code.visualstudio.com/docs/editor/tasks), in a similar fashion.
        
        
        <br>
        
        
        ## Python API
        
        ```python
        import coblack
        
        coblack.format_file("path/to/my_file.py")  # You can also pass a `pathlib.Path`.
        ```
        
        
        <br>
        
        
        ## Appendix
        
        #### Naive way of wrapping comments
        
        ```python
        def care_for(self, favorite_plant):
            self.sing_a_lullaby_to(favorite_plant)  # This should help them grow. Note that this
            # comment is too long to fit on one line, given the recommended line length.
            favorite_plant.water(100 * mL)  # Prevent dehydration.
        ```
        ([👆 back to top of ReadMe](#coblack)).
        
        
        <br>
        
        #### Other comment styles
        
        On own line, before code:
        ```python
        def care_for(self, favorite_plant):
            
            # This should help them grow. Note that this comment is too long to fit on one line,
            # given the recommended line length.
            self.sing_a_lullaby_to(favorite_plant)
        
            # Prevent dehydration.
            favorite_plant.water(100 * mL)
        ```
        
        On own line, after code:
        ```python
        def care_for(self, favorite_plant):
            
            self.sing_a_lullaby_to(favorite_plant)
            # This should help them grow. Note that this comment is too long to fit on one line,
            # given the recommended line length.
            
            favorite_plant.water(100 * mL)
            # Prevent dehydration.
        ```
        
        These styles don't need _CoBlack_;
        a vanilla rewrapper like any of the following will do:
        - The [Wrap to Column](https://plugins.jetbrains.com/plugin/7234-wrap-to-column) plugin for PyCharm;
        - The [Rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) extension for VS Code;
        - The "Wrap Paragraph at Ruler" command in Sublime Text (`Alt-Q` or `Alt-⌘-Q`) ;
        - The `fill-paragraph` command in Emacs; or
        - The `gq` operator in Vim.
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >= 3.8
Description-Content-Type: text/markdown
