Skip to content

Commit

Permalink
Documented use as a library
Browse files Browse the repository at this point in the history
  • Loading branch information
spookylukey committed Nov 28, 2023
1 parent 5badd1f commit e310b63
Show file tree
Hide file tree
Showing 4 changed files with 75 additions and 3 deletions.
3 changes: 2 additions & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ of grepping for string matches.
The interface and behaviour is designed to match grep and ripgrep as far as it
makes sense to do so.

Documentation: in the process of migration to readthedocs, see docs/ for now.
See `the documentation <https://pyastgrep.readthedocs.io/>`_ for more
information, or the ``docs`` folder.


History
Expand Down
5 changes: 5 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

extensions = [
"sphinx_rtd_theme",
"sphinx.ext.intersphinx",
]

templates_path = ["_templates"]
Expand All @@ -30,3 +31,7 @@


pygments_style = "sphinx"

# --- Extensions

intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
1 change: 1 addition & 0 deletions docs/history.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Version 1.3.2 - unreleased
--------------------------

* Fixed various crashers for permission errors or broken files
* Documented API for use as a library.

Version 1.3.1 - 2023-07-19
--------------------------
Expand Down
69 changes: 67 additions & 2 deletions docs/library.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,75 @@ Use as a library
pyastgrep is structured internally to make it easy to use as a library as well
as a CLI, with a clear separation of the different layers. For now, the
following API is documented as public and we will strive to maintain backwards
compatibility with these things:
compatibility with it:

TODO
.. currentmodule:: pyastgrep.api

.. function:: search_python_files(paths, expression)

Searches for files with AST matching the given XPath ``expression``, in the given ``paths``.

If ``paths`` contains directories, then all Python files in that directory
and below will be found, but ``.gitignore`` and other rules are used to
ignore files and directories automatically.

Returns an iterable of :class:`Match` object, plus other objects.

The other objects are used to indicate errors, usually things like a failure to parse a file that had a ``.py`` extension. The details of these other objects are not being documented yet, so use at own risk, and ensure that you filter the results by doing an ``isinstance`` check for the ``Match`` objects.

:param paths: List of paths to search, which can be files or directories, of type :class:`pathlib.Path`
:type paths: list[pathlib.Path]

:param expression: XPath expression

:type expression: str

:return: Iterable[Match | Any]




.. class:: Match

Represents a matched AST node. The public properties of this are:

.. property:: path

The path of the file containing the match.

:type: pathlib.Path

.. property:: position

The position of the matched AST node within the Python file.

:type: :class:`Position`

.. property:: ast_node

The AST node object matched

:type: ast.AST

.. property:: matching_line

The text of the whole line that matched

:type: str

.. class:: Position

.. property:: lineno

Line number, 1-indexed, as per AST module

:type: int

.. property:: col_offset

Column offset, 0-indexed, as per AST module

:type: int


For other things, we while we will try not to break things without good reason,
Expand Down

0 comments on commit e310b63

Please sign in to comment.