Metadata-Version: 2.1
Name: commie
Version: 1.0.5
Summary: Extracts comments from source code in different programming languages
Home-page: https://github.com/rtmigo/commie
Author: Art Galkin
Author-email: ortemeo@gmail.com
License: BSD-3-Clause
Description: #  [commie](https://github.com/rtmigo/commie)
        
        Native Python package for **extracting comments** from source code.
        
        Multiple programming and markup languages are
        supported: [see list](https://github.com/rtmigo/commie.python#find-comments-in-a-string).
        
        # Install
        
        ```sh
        $ pip3 install commie
        ```
        
        # Find comments in a file
        
        ``` python
        from pathlib import Path
        import commie
        
        for comment in commie.iter_comments(Path("/path/to/source.cpp")):
        
            # something like "/* sample */"
            print("Comment code:", comment.code)
            print("Comment code location:", comment.code_span.start, comment.code_span.end)
            
            # something like " sample " 
            print("Comment inner text:", comment.text)
            print("Comment text location:", comment.text_span.start, comment.text_span.end)
        ```
        
        # Find comments in a string
        
        | **Method** | **Works for** |
        |--------------------|------------|
        | `commie.iter_comments_c`| C, C++, C#, Java, Objective-C, JavaScript, Dart, TypeScript |
        | `commie.iter_comments_go`|Go|
        | `commie.iter_comments_ruby` | Ruby |
        | `commie.iter_comments_python` | Python |
        | `commie.iter_comments_shell` | Bash, Sh |
        | `commie.iter_comments_html` | HTML, XML, SGML |
        | `commie.iter_comments_css` | CSS |
        | `commie.iter_comments_sass` | SASS |
        
        ``` python
        import commie
        
        source_code_in_golang:str = ...
        
        for comment in commie.iter_comments_go(source_code_in_golang):
            # ... process comment ...
            pass
        ```
        
        # Find comments in a string with a known filename
        
        Method `commie.iter_comments` will try to guess the file format from the provided filename.
        
        ``` python
        from pathlib import Path
        import commie
        
        filename: str = "/path/to/mycode.go"
        source_code: str = Path(filename).read_text()
        
        for comment in commie.iter_comments(source_code, filename=filename):
            # ... process comment ...
            pass
        ```
        
        # Group single line comments
        
        When single-line comments are adjacent, it makes sense to consider them together:
        
        ```cpp
        // Group A: A short comment
        
        // Group B: It consists of three
        // single-line comments with 
        // no empty lines between them
        
        // Group C: This paragraph loosely 
        // stretched into two lines  
        ```
        
        The comments from the example above can be combined into **three groups** as follows:
        
        ``` python
        from commie import iter_comments, group_singleline_comments
        
        for group in group_singleline_comments(iter_comments(...)):
            # ... each group is a list of Comment objects ...
            pass
        ```
        
        Multi-line comments will also be returned. They will not be grouped with their neighbors.
        
        --------------------------------------------------------
        
        This project was forked from [comment_parser](https://github.com/jeanralphaviles/comment_parser) in
        2021. Motivation:
        
        | **comment_parser** | **commie** |
        |--------------------|------------|
        |Returns only a line number|Returns positions where the comment starts and ends. Just like regular string search|
        |Returns only the text of a comment|Respects markup as well, making it possible to remove or replace the entire comment|
        |Depends on [python-magic](https://pypi.org/project/python-magic) that requires an optional installation of binaries|Pure Python. Easy to install with `pip`|
        
        As for now it's too different from `comment_parser`, so the changes will not be pushed there.
        
        
Keywords: css,python,c,search,java,go,html,sass,c-sharp,dart,bash,parser,typescript,parsing,xml,comments,source-code
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Software Development :: Documentation
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
