<commit_before>.. _using-api-graphs-in-python:

Using API graphs in Python
==========================

API graphs are a uniform interface for referring to functions, classes, and methods defined in
external libraries.

About this article
------------------

This article describes how to use API graphs to reference classes and functions defined in library
code. You can use API graphs to conveniently refer to external library functions when defining things like
remote flow sources.


Module imports
--------------

The most common entry point into the API graph will be the point where an external module or package is
imported. For example, you can access the API graph node corresponding to the ``re`` library
by using the ``API::moduleImport`` method defined in the ``semmle.python.ApiGraphs`` module, as the
following snippet demonstrates.

.. code-block:: ql

    import python
    import semmle.python.ApiGraphs

    select API::moduleImport("re")

➤ `See this in the query console on LGTM.com <https://lgtm.com/query/1876172022264324639/>`__.

This query selects the API graph node corresponding to the ``re`` module. This node represent the fact that the ``re`` module has been imported rather than a specific place in the program where the import happens. Therefore, there will be at most one result per project, and it will not have a useful location, so you have to click `Show 1 non-source result` in order to see it.

To find places in the program where the ``re`` module is referenced, you can use the ``getAUse`` method. The following query selects all references to the ``re`` module in the current database.

.. code-block:: ql

    import python
    import semmle.python.ApiGraphs

    select API::moduleImport("re").getAUse()

➤ `See this in the query console on LGTM.com <https://lgtm.com/query/8072356519514905526/>`__.

Note that the ``getAUse`` method accounts for local flow, so that ``my_re_compile``
in the following snippet is
correctly recognized as a reference to the ``re.compile`` function.

.. code-block:: python

    from re import compile as re_compile

    my_re_compile = re_compile

    r = my_re_compile(".*")

If you only require immediate uses, without taking local flow into account, then you can use
the ``getAnImmediateUse`` method instead.<commit_msg>Apply suggestions from code review<commit_after>.. _using-api-graphs-in-python:

Using API graphs in Python
==========================

API graphs are a uniform interface for referring to functions, classes, and methods defined in
external libraries.

About this article
------------------

This article describes how to use API graphs to reference classes and functions defined in library
code. You can use API graphs to conveniently refer to external library functions when defining things like
remote flow sources.


Module imports
--------------

The most common entry point into the API graph will be the point where an external module or package is
imported. For example, you can access the API graph node corresponding to the ``re`` library
by using the ``API::moduleImport`` method defined in the ``semmle.python.ApiGraphs`` module, as the
following snippet demonstrates.

.. code-block:: ql

    import python
    import semmle.python.ApiGraphs

    select API::moduleImport("re")

➤ `See this in the query console on LGTM.com <https://lgtm.com/query/1876172022264324639/>`__.

This query selects the API graph node corresponding to the ``re`` module. This node represents the fact that the ``re`` module has been imported rather than a specific location in the program where the import happens. Therefore, there will be at most one result per project, and it will not have a useful location, so you'll have to click `Show 1 non-source result` in order to see it.

To find where the ``re`` module is referenced in the program, you can use the ``getAUse`` method. The following query selects all references to the ``re`` module in the current database.

.. code-block:: ql

    import python
    import semmle.python.ApiGraphs

    select API::moduleImport("re").getAUse()

➤ `See this in the query console on LGTM.com <https://lgtm.com/query/8072356519514905526/>`__.

Note that the ``getAUse`` method accounts for local flow, so that ``my_re_compile``
in the following snippet is
correctly recognized as a reference to the ``re.compile`` function.

.. code-block:: python

    from re import compile as re_compile

    my_re_compile = re_compile

    r = my_re_compile(".*")

If you only require immediate uses, without taking local flow into account, then you can use
the ``getAnImmediateUse`` method instead.
{'fraction_non_alphanumeric': 0.09417622862091361, 'fraction_numerical': 0.016886772028577614, 'mean_word_length': 4.0, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7059290', 'n_tokens_mistral': 1255, 'n_tokens_neox': 1177, 'n_words': 620}