Hooks

Introduction

Hooks allow you to define your own callbacks that can be executed at certain parts of the actions newsreap performs.

The Decorator

There are many ways to utilize hooks, either use a python file someone else prepared that has all the hooks you want defined already in it like so:

# The following will allow you to add a hook while downloading
# the contents of my.favourite.thing.nzb
nr get --hooks=/path/to/your.hook.py my.favourite.thing.nzb

# The 'get' command always looks in the newsreap/hooks/get directory
# so if there was a file called myhook.py within there, then this
# would work too:
nr get --hooks=myhook my.favourite.thing.nzb

# If you want to specify more then one hook, just use a comma to
# delimit one from another:
nr get --hooks=myhook,myotherhook,/path/to/hook3.py my.favourite.thing.nzb

Write your own hook

from newsreap.decorators import hook

@hook
def pre_download(**kwargs):
   # write your function here, **kwargs provides all of the options
   # you'll be passed.  It's a good idea to always include that in
   # the function even if you know in advance what to expect.
   # In this example, if someone pointed to the file this function
   # exists to (as a hook), this code would get executed every time
   # a download is about to begin.

   results = kwargs.get('results')
   if results:
      print('We've got results to work with!')

   pass

@hook(name='post_download')
def get_subtitles_for_my_favourite_shows(name, path, status, results, **kwargs):
   """
   There are lots of things to take from this example
      1. i can call the function something different then the hook name
         as long as i let the decorator know what this function should be
         called on.

      2. Although i'm still using **kwargs, since I know some variables that
         will be available to me, i can directly reference them as parameters.
         **kwargs allows for new stuff to be added over time and your existing
         hooks will always still work! So don't forget to include that entry
         at the very least.
   """
   if status is True:
      print('Our download was successful!')

   if results:
      print('We've got results to work with!')

@hook(name='post_download', priority=1)
def password_checker(name, path, status, nzb, **kwargs):
   """
   This just introduces the reference to the keyword priority.  By default
   every hook has a priority of 1000.  This is effectively the sort order
   of when this function will be called with respect to all of the other hooks
   defined. The lower the number'ed entries are called before the higher ones

   There is no limitation, if you want to set this number to -9999 then do so.

   """

The Hooks

Hook	Group	Details
pre_download	factory_io	Is called just before a download is about to be orchestrated using the CLI and/or NNTPGetFactory(). This is a high level hook that allows you to access and/or manipulate NZB-Files and/or Message-IDs being queried for download purposes. If you define a custom hook around this and have it return False, you will over-throw the action and prevent the download from happening.
post_download	factory_io	Is called after a download has completed. Even if the entire download fails, this hook will still get called. You will have access to the success of the transfer as well as access to the location all of the downloaded content resides in. This is a fantastic hook for adding your own extra manipulations and post processing.
pre_post	nntp_io	Is called just before an Article is about to be posted to an NNTP Server. If you define a custom hook around this and have it return False, you will over-throw the action and prevent the upload from happening. You have the ability to mangle/adjust the Article in this hook too if you desire.
post_post	nntp_io	Is called just after an Article was sent to an NNTP Server. Even if the transfer of it fails, this hook will still get called. You will have access to the success of the transfer from within the hook.
pre_get	nntp_io	Is called just before an Article is about to be downloaded from an NNTP Server. If you define a custom hook around this and have it return False, you will over-throw the action and prevent the download from happening.
post_get	nntp_io	Is called just after an Article was retrieved from an NNTP Server. Even if the transfer of it fails, this hook will still get called. You will have access to the success of the transfer as well as access to the Article itself from within the hook.
pre_xover	nntp_io	Is called just before an XOVER call is about to be issued to an NNTP Server. If you define a custom hook around this and have it return False, you will over-throw the action and prevent it from happening.
post_xover	nntp_io	Is called just after an XOVER was sent to an NNTP Server and it's actions have been completed. Even if the action failed, this hook will still get called. You will have access to the success of the XOVER from within the hook.
pre_stat	nntp_io	Is called just before a STAT or HEAD call is about to be issued to an NNTP Server. If you define a custom hook around this and have it return False, you will over-throw the action and prevent it from happening.
post_stat	nntp_io	Is called just after a STAT or HEAD was sent to an NNTP Server and it's actions have been completed. Even if the action failed, this hook will still get called. You will have access to the success of the action from within the hook.
pre_connect	nntp_io	Is called just before an attempt to an NNTP Server is preformed. If you define a custom hook around this and have it return False you will over-throw the connection and stop it from happening.
post_connect	nntp_io	Is called just after an attempt to an NNTP Server is preformed. Even if the connection fails, this hook will still get called. You will have access to the success of the connect from within the hook.
socket_read	io	A very low level call that is executed whenever data is read from the socket. It's useful for calculating transfer speeds.
socket_write	io	A very low level call that is executed whenever data is written to the socket. It's useful for calculating transfer speeds.
socket_connect	io	A very low level call that is executed whenever a connection is established to an NNTP Server. This hook only gets called if the connection is successfully established (at a TCP/IP level).
socket_close	io	A very low level call that is executed whenever a connection dropped/closed from an NNTP Server.