comment-parser


Namecomment-parser JSON
Version 1.2.5 PyPI version JSON
download
home_pagehttp://github.com/jeanralphaviles/comment_parser
SummaryParse comments from various source files.
upload_time2024-12-25 05:08:14
maintainerNone
docs_urlNone
authorJean-Ralph Aviles
requires_python>=3.13
licenseMIT
keywords
VCS
bugtrack_url
requirements python-magic
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Comment Parser

[![Run Tests](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml)
[![PyPI status](https://img.shields.io/pypi/status/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)
[![PyPI version shields.io](https://img.shields.io/pypi/v/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)
[![PyPI license](https://img.shields.io/pypi/l/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)

Python module used to extract comments from source code files of various types.

## Installation

### Prerequisites

* libmagic

### Linux/Unix

```shell
sudo pip3 install comment_parser
```

### OSX and Windows

Additionally, complete the special installation requirements for
[python-magic](https://github.com/ahupp/python-magic).

## Usage

To use, simply run:

```python
>>> from comment_parser import comment_parser
>>> # Returns a list of comment_parser.parsers.common.Comments
>>> comment_parser.extract_comments('/path/to/source_file')
>>> # Or
>>> comment_parser.extract_comments_from_str('...')
```

### extract_comments signatures

```python
def extract_comments(filename, mime=None):
    """Extracts and returns the comments from the given source file.

    Args:
        filename: String name of the file to extract comments from.
        mime: Optional MIME type for file (str). Note some MIME types accepted
            don't comply with RFC2045. If not given, an attempt to deduce the
            MIME type will occur.
    Returns:
        Python list of parsers.common.Comment in the order that they appear in
            the source file.
    Raises:
        UnsupportedError: If filename is of an unsupported MIME type.
    """
    pass


def extract_comments_from_str(code, mime=None):
    """Extracts and returns comments from the given source string.

    Args:
        code: String containing code to extract comments from.
        mime: Optional MIME type for code (str). Note some MIME types accepted
            don't comply with RFC2045. If not given, an attempt to deduce the
            MIME type will occur.
    Returns:
        Python list of parsers.common.Comment in the order that they appear in
            the source code.
    Raises:
        UnsupportedError: If code is of an unsupported MIME type.
    """
    pass
```

### Comments Interface

```python
class Comment(object):
    """Represents comments found in source files."""
    def text(self):
        """Returns the comment's text.
        Returns:
            String
        """
        pass

    def line_number(self):
        """Returns the line number the comment was found on.
        Returns:
            Int
        """
        pass

    def is_multiline(self):
        """Returns whether this comment was a multiline comment.
        Returns:
            True if comment was a multiline comment, False if not.
        """
       pass

    def __str__(self):
        pass

    def __eq__(self, other):
        pass
```

## Development

### Install Dependencies

```shell
pip install -r requirements.txt -r requirements-dev.txt
```

### Running locally

Start python in the base of repository.

```python
from comment_parser import comment_parser
comment_parser.extract_comments('foo.c', mime='text/x-c')
```

### Running tests

```shell
python -m pytest
```

### Running pylint

```shell
pylint comment_parser
```

### Running formatter

```shell
yapf -rip .
```

### Deploying to PyPi

```shell
python setup.py sdist
twine upload dist/*
```

## Supported Programming Languages

| Language    | Mime String              |
|------------ |------------------------- |
| C           | text/x-c                 |
| C++/C#      | text/x-c++               |
| Go          | text/x-go                |
| HTML        | text/html                |
| Java        | text/x-java-source       |
| Javascript  | application/javascript   |
| Python      | text/x-python            |
| Python      | text/x-script.python     |
| Ruby        | text/x-ruby              |
| Shell       | text/x-shellscript       |
| XML         | text/xml                 |

And more to come!

*Check comment_parser.py for corresponding MIME types.*



            

Raw data

            {
    "_id": null,
    "home_page": "http://github.com/jeanralphaviles/comment_parser",
    "name": "comment-parser",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.13",
    "maintainer_email": null,
    "keywords": null,
    "author": "Jean-Ralph Aviles",
    "author_email": "jeanralph.aviles+pypi@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/37/6a/354d8e640b5f90996ac07c002189a552226a0ddaad85efd14863166aaa14/comment_parser-1.2.5.tar.gz",
    "platform": null,
    "description": "# Comment Parser\n\n[![Run Tests](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml)\n[![PyPI status](https://img.shields.io/pypi/status/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)\n[![PyPI version shields.io](https://img.shields.io/pypi/v/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)\n[![PyPI license](https://img.shields.io/pypi/l/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)\n[![PyPI pyversions](https://img.shields.io/pypi/pyversions/comment_parser.svg)](https://pypi.python.org/pypi/comment_parser/)\n\nPython module used to extract comments from source code files of various types.\n\n## Installation\n\n### Prerequisites\n\n* libmagic\n\n### Linux/Unix\n\n```shell\nsudo pip3 install comment_parser\n```\n\n### OSX and Windows\n\nAdditionally, complete the special installation requirements for\n[python-magic](https://github.com/ahupp/python-magic).\n\n## Usage\n\nTo use, simply run:\n\n```python\n>>> from comment_parser import comment_parser\n>>> # Returns a list of comment_parser.parsers.common.Comments\n>>> comment_parser.extract_comments('/path/to/source_file')\n>>> # Or\n>>> comment_parser.extract_comments_from_str('...')\n```\n\n### extract_comments signatures\n\n```python\ndef extract_comments(filename, mime=None):\n    \"\"\"Extracts and returns the comments from the given source file.\n\n    Args:\n        filename: String name of the file to extract comments from.\n        mime: Optional MIME type for file (str). Note some MIME types accepted\n            don't comply with RFC2045. If not given, an attempt to deduce the\n            MIME type will occur.\n    Returns:\n        Python list of parsers.common.Comment in the order that they appear in\n            the source file.\n    Raises:\n        UnsupportedError: If filename is of an unsupported MIME type.\n    \"\"\"\n    pass\n\n\ndef extract_comments_from_str(code, mime=None):\n    \"\"\"Extracts and returns comments from the given source string.\n\n    Args:\n        code: String containing code to extract comments from.\n        mime: Optional MIME type for code (str). Note some MIME types accepted\n            don't comply with RFC2045. If not given, an attempt to deduce the\n            MIME type will occur.\n    Returns:\n        Python list of parsers.common.Comment in the order that they appear in\n            the source code.\n    Raises:\n        UnsupportedError: If code is of an unsupported MIME type.\n    \"\"\"\n    pass\n```\n\n### Comments Interface\n\n```python\nclass Comment(object):\n    \"\"\"Represents comments found in source files.\"\"\"\n    def text(self):\n        \"\"\"Returns the comment's text.\n        Returns:\n            String\n        \"\"\"\n        pass\n\n    def line_number(self):\n        \"\"\"Returns the line number the comment was found on.\n        Returns:\n            Int\n        \"\"\"\n        pass\n\n    def is_multiline(self):\n        \"\"\"Returns whether this comment was a multiline comment.\n        Returns:\n            True if comment was a multiline comment, False if not.\n        \"\"\"\n       pass\n\n    def __str__(self):\n        pass\n\n    def __eq__(self, other):\n        pass\n```\n\n## Development\n\n### Install Dependencies\n\n```shell\npip install -r requirements.txt -r requirements-dev.txt\n```\n\n### Running locally\n\nStart python in the base of repository.\n\n```python\nfrom comment_parser import comment_parser\ncomment_parser.extract_comments('foo.c', mime='text/x-c')\n```\n\n### Running tests\n\n```shell\npython -m pytest\n```\n\n### Running pylint\n\n```shell\npylint comment_parser\n```\n\n### Running formatter\n\n```shell\nyapf -rip .\n```\n\n### Deploying to PyPi\n\n```shell\npython setup.py sdist\ntwine upload dist/*\n```\n\n## Supported Programming Languages\n\n| Language    | Mime String              |\n|------------ |------------------------- |\n| C           | text/x-c                 |\n| C++/C#      | text/x-c++               |\n| Go          | text/x-go                |\n| HTML        | text/html                |\n| Java        | text/x-java-source       |\n| Javascript  | application/javascript   |\n| Python      | text/x-python            |\n| Python      | text/x-script.python     |\n| Ruby        | text/x-ruby              |\n| Shell       | text/x-shellscript       |\n| XML         | text/xml                 |\n\nAnd more to come!\n\n*Check comment_parser.py for corresponding MIME types.*\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Parse comments from various source files.",
    "version": "1.2.5",
    "project_urls": {
        "Homepage": "http://github.com/jeanralphaviles/comment_parser"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "376a354d8e640b5f90996ac07c002189a552226a0ddaad85efd14863166aaa14",
                "md5": "d710cc70eda8de85cd920782aeb3b4bf",
                "sha256": "5606b769228cafce03d538e361472896581b386f3bc44bd62f4b61ff45ff05ec"
            },
            "downloads": -1,
            "filename": "comment_parser-1.2.5.tar.gz",
            "has_sig": false,
            "md5_digest": "d710cc70eda8de85cd920782aeb3b4bf",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.13",
            "size": 8852,
            "upload_time": "2024-12-25T05:08:14",
            "upload_time_iso_8601": "2024-12-25T05:08:14.618600Z",
            "url": "https://files.pythonhosted.org/packages/37/6a/354d8e640b5f90996ac07c002189a552226a0ddaad85efd14863166aaa14/comment_parser-1.2.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-25 05:08:14",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "jeanralphaviles",
    "github_project": "comment_parser",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "python-magic",
            "specs": [
                [
                    "==",
                    "0.4.27"
                ]
            ]
        }
    ],
    "lcname": "comment-parser"
}
        
Elapsed time: 0.57830s