# Comment Parser
[](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml)
[](https://pypi.python.org/pypi/comment_parser/)
[](https://pypi.python.org/pypi/comment_parser/)
[](https://pypi.python.org/pypi/comment_parser/)
[](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[](https://github.com/jeanralphaviles/comment_parser/actions/workflows/test.yml)\n[](https://pypi.python.org/pypi/comment_parser/)\n[](https://pypi.python.org/pypi/comment_parser/)\n[](https://pypi.python.org/pypi/comment_parser/)\n[](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"
}
JSON
