Welcome to Asya’s documentation!¶
Introduction¶
ASynchronously-Your-Acquaintances is simple Python-powered asynchronous client for GitHub API that allows you to list acquaitances from GitHub issues = all people who commented the issues in which is given user involved (author, commenter, assigned, mentioned). It has of course the ability to filter issues.
How it works¶
As the name says, it is asynchronous - so all requests are made asynchronously making the tool
quite faster than classic synchronous approach. It uses asyncio and aiohttp. Task done by
this tool can be sometimes quite complex and reaches a limits of GitHub API. For extending API
rate limit you can provide personal access token via --token. Nevertheless, it may happen
that you reach limit even with that - you can use --wait_rate_limit flag and application
will quietly wait until the limit resets (about 1 hour). Other problem is that GitHub Search API
provides only 1000 results so you need to use filter & sort appropriately in some cases.
MI-PYT¶
Task for MI-PYT course (FIT, CTU in Prague, 2017/18) is to implement the core module of this
application which is asya.logic. Mandatory is to use asyncio, aiohttp and call
appropriate methods on the supervisor object of asya.supervisor.AsyaSupervisor class.
Installation¶
You can simply install Asya in standard Python way (system-wide or with virtual env). Python 3.4 or higher is required (asyncio is in Python since 3.4).
python setup.py install
Usage¶
After installation, you can use the CLI of Asya (for more, visit CLI docs):
asya --help
asya MarekSuchanek --token <your-secret-API-token>
License¶
This project is licensed under the MIT License (see the LICENSE file for more details).
CLI¶
asya¶
Asya Command Line Interface (via click)
asya [OPTIONS] USERNAME
Options
-
-i,--involvement<involvement>¶ How is given user involved in issues.
-
--text<text>¶ Text to filter issues.
-
--in<in>¶ In what should be text searched.
-
--type<type>¶ Restriction to just issues or just PRs.
-
--state<state>¶ Restriction to just issues or just PRs.
-
--created<created>¶ Date expression to filter by created date.
-
--updated<updated>¶ Date expression to filter by updated date.
-
--label<label>¶ String to filter by label.
-
--language<language>¶ String to filter by language.
-
--sort<sort>¶ Sort search results (important for >1000 results).
-
--order<order>¶ Sort order of results (important for >1000 results).
-
-t,--token<token>¶ Personal GitHub token.
-
-w,--wait-rate-limit¶ Wait for rate limit reset if needed.
-
-s,--skip-404¶ Skip not-found GitHub resources (such as disabled repos).
-
-b,--progress-bar¶ Toggle progress bar (default false).
-
--info,--no-info¶ Toggle info texts (default true).
-
--api-endpoint<api_endpoint>¶ How is given user involved in issues.
-
--debug¶ Debug mode (not catching other exceptions).
-
--version¶ Show the version and exit.
Arguments
-
USERNAME¶ Required argument
Environment variables
API¶
asya.cli¶
-
asya.cli.create_search_specs(username, sort, order, text, involvement, query_opts)¶ Create GitHub issues search specification (params dict)
-
asya.cli.no_print(*args, **kwargs)¶ Dummy method for not actually printing anything
-
asya.cli.print_result(result)¶ Print Asya result nicely
-
asya.cli.setup_info_msgs(supervisor)¶ Setup text info printing for given supervisor
-
asya.cli.setup_progressbar(supervisor)¶ Setup progressbar for given supervisor
asya.exceptions¶
asya.logic¶
Important
This is the module to be implemented!
-
asya.logic.gather_acquaintances(search_specs, supervisor)¶ Gather acquaintances from GitHub issues and comments with given search_specs with counts of comments in form of dict. It uses
asyncioandaiohttp.ClientSession.>>> gather_acquaintances({'q': 'author:MarekSuchanek'}, supervisor) {'MarekSuchanek': 7, 'hroncok': 15, 'encukou': 10}
For more information about the
search_specscontent visit the GitHub Search API docs.Parameters: - search_specs (dict) – dictionary with search specification (params for the search)
- supervisor (asya.supervisor.AsyaSupervisor) – supervisor object used for this gathering
Returns: dictionary with usernames as keys and number of comments as values
Return type:
asya.supervisor¶
-
class
asya.supervisor.AsyaSupervisor(api_endpoint, token, wait_rate_limit, skip_404, per_page=100)¶ Supervisor for running the Asya gathering async procedure. It contains some procedure-wide setting and calls.
The
gather_acquaintancesfunction must call supervisor’sreport_methods at the right places (described in docstrings):... # receiving and processing the issue supervisor.report_issue(issue) # additional work with the issue ...
Your implementation may add custom callbacks:
def my_procedure(issue): ... supervisor.callbacks['issue'].append(my_procedure) # my_procedure will be called when report_issue is # called on the supervisor object
You may also use
supervisor.objfor your data as you need. Do not touch other parameters nor edit this class!Variables: - api_endpoint – API endpoint to be used for communication
- token – API token to be used (you can use
has_token) - wait_rate_limit – True if the app should wait until the rate limit resets after it is
exceeded, False if exceeding the limit should cause
AsyaException - skip_404 – True the app should skip 404 errors, False if they should
raise
AsyaException - per_page – size of page for API requests
-
has_token¶ True if the API token is set
-
obj= None¶ User obj (can be anything)
-
report_comment(comment)¶ Method to be called after processing of a single comment
Parameters: comment (dict) – GitHub comment (data from API)
-
report_issue(issue)¶ Method to be called after processing of a single issue
Parameters: issue (dict) – GitHub issue (data from API)
-
report_issues_search_page(page, number)¶ Method to be called before processing of a single result page
Parameters: