Tools¶

This are the tools for the user using Photon. You should not directly use them, instead they will get provided to you by Photon.

See also

Settings, Meta, Photon

Some functionality here is bought from the Utility:

See also

Files, Locations, Structures, System

Git Tool¶

class photon.tools.git.Git(m, local, remote_url=None, mbranch=None)[source]¶

The git tool helps to deal with git repositories.

Parameters:

local –
The local folder of the repository
- If None given (default), it will be ignored if there is already a git repo at local
- If no git repo is found at local, a new one gets cloned from remote_url
remote_url –
The remote URL of the repository
- Tears down (using util.system.shell_notify() with state set to True) whole application if remote_url is set to None but a new clone is necessary
mbranch – The repository’s main branch. Is set to master when left to None

_checkout(treeish)[source]¶

Helper function to checkout something

Parameters:	treeish – String for ‘tag‘, ‘branch‘, or remote tracking ‘-B banch‘

_get_branch(remotes=False)[source]¶

Helper function to determine current branch

Parameters:	remotes – List the remote-tracking branches

_get_remote(cached=True)[source]¶

Helper function to determine remote

Parameters:	cached – Use cached values or query remotes

_log(num=None, format=None)[source]¶

Helper function to receive git log

Parameters:	num – Number of entries format – Use formatted output with specified format string

_pull()[source]¶: Helper function to pull from remote

branch¶

Parameters:	branch – Checks out specified branch (tracking if it exists on remote). If set to `None`, ‘master’ will be checked out
Returns:	The current branch (This could also be ‘master (Detatched-Head)’ - Be warned)

cleanup¶

Commits all local changes (if any) into a working branch, merges it with ‘master’.

Checks out your old branch afterwards.

Tears down (using util.system.shell_notify() with state set to True) whole application if conflicts are discovered

commit¶

Parameters:	tag – Checks out specified commit. If set to `None` the latest commit will be checked out
Returns:	A list of all commits, descending

local¶

Returns:	The local folder of the repository

log¶

Returns:	The last 10 commit entries as dictionary

‘commit’: The commit-ID
‘message’: First line of the commit message

publish¶: Runs cleanup() first, then pushes the changes to the remote.

remote¶

Returns:	Current remote

remote_url¶

Returns:	The remote URL of the repository

short_commit¶

Returns:	A list of all commits, descending

See also

commit

status¶

Returns:	Current repository status as dictionary:

‘clean’: True if there are no changes False otherwise
‘untracked’: A list of untracked files (if any and not ‘clean’)
‘modified’: A list of modified files (if any and not ‘clean’)
‘deleted’: A list of deleted files (if any and not ‘clean’)
‘conflicting’: A list of conflicting files (if any and not ‘clean’)

tag¶

Parameters:	tag – Checks out specified tag. If set to `None` the latest tag will be checked out
Returns:	A list of all tags, sorted as version numbers, ascending

Mail Tool¶

class photon.tools.mail.Mail(m, to, sender, subject=None, cc=None, bcc=None)[source]¶

The Mail tool helps to send out mails.

Parameters:	to – Where to send the mail ('user@example.com‘) sender – Yourself ('me@example.com‘) set a reverse DNS entry for `example.com` so your mail does not get caught up in spamfilters. subject – The subject line cc – One or a list of CCs bcc – One or a list of BCCs

send¶

Returns:	A dictionary with the following: ‘sender’: The sender ‘recipients’: All recipients, compiled from to, cc and bcc ‘result’: The `smtplib.SMTP.sendmail()`-result ‘exception’: The exception message (if any)

Note

You need to have a postfix/sendmail running and listening on localhost.

text¶

Parameters:	text – Add some more text
Returns:	All text & headers as raw mail source

Mail Tool Example¶

mail.sample.yaml

mail:
    recipient: you@example.com
    sender: me@example.com
    subject: 'Fire!'
    punchline: 'Dear Sir or Madam, I am writing to inform you about a fire in the building ...'

mail.sample.py

from photon import Photon

photon = Photon('mail.sample.yaml')

settings = photon.settings.get['mail']

mail = photon.mail_handler(
    to=settings['recipient'],
    sender=settings['sender'],
    subject=settings['subject'],
    punchline=settings['punchline'],
    add_meta=True
)

###
# Shows the message source so far
print(mail.text)

###
# Add some more text (do this as often as you like):
mail.text = '''
Dear Sir or Madam,
bla bla

No, that's too formal..
'''

###
# Guess what happens here:
mail.send

Ping Tool¶

class photon.tools.ping.Ping(m, six=False, net_if=None, num=5, packetsize=None, max_pool_size=None)[source]¶

The Ping tool helps to send pings, returning detailed results each probe, and calculates a summary of all probes.

Parameters:

six – Either use ping or ping6
net_if – Specify network interface to send pings from
num – How many pings to send each probe
packetsize – Specifies the number of data bytes to be sent
max_pool_size – Hosts passed to probe() in form of a list, will be processed in parallel. Specify the maximum size of the thread pool workers here. If skipped, the number of current CPUs is used

probe¶

Parameters:

hosts –

One or a list of hosts (URLs, IP-addresses) to send pings to

If you need to check multiple hosts, it is best to pass them together as a list.
This will probe all hosts in parallel, with max_pool_size workers.

Returns: A dictionary with all hosts probed as keys specified as following:

‘up’: True or False depending if ping was successful
‘loss’: The packet loss as list (if ‘up’)
‘ms’: A list of times each packet sent (if ‘up’)
‘rtt’: A dictionary with the fields avg, min, max & stddev (if ‘up’)

status¶

Returns:	A dictionary with the following:

‘num’: Total number of hosts already probed
‘up’: Number of hosts up
‘down’: Number of hosts down
‘ratio’: Ratio between ‘up’/’down’ as float

Ratio:

100% up == 1.0
10% up == 0.1
0% up == 0.0

Ping Tool Example¶

ping.sample.yaml

hosts:
    addresses:
    - '127.0.0.1'
    - '127.0.0.2'
    - '127.0.0.3'
    urls:
    - exampla.com
    - example.com
    - exampli.com
    - examplo.com
    - examplu.com

ping.sample.py

from pprint import pprint

from photon import Photon

photon = Photon('ping.sample.yaml')

hosts = photon.settings.get['hosts']

ping = photon.ping_handler()

###
# Let's start off with localhost to demonstrate the handling
# of the probe-function:

pprint(hosts)

a = hosts['addresses'][0]
ping.probe = a

if ping.probe[a]['up']:
    print('%s is reachable - %s ms rtt in average' % (
        a, ping.probe[a]['rtt']['avg']
    ))
else:
    print('%s could not be reached!' % (a))

pprint(ping.probe)

print('-' * 8)


###
# You can also pass a complete list to probe. This will be faster, because
# the list is processed in parallel.
# The status per host will be overwritten with new information if it
# encounters the same host again:

ping.probe = hosts['addresses']
pprint(ping.probe)

print('These are the statistics so far:')
pprint(ping.status)

print('-' * 8)


###
# Another round of pings to demonstrate the handling of the status-function:

ping.probe = hosts['urls']

if ping.status['ratio'] <= 0.75:
    print('more than three quarters of all addresses are not reachable!!1!')

print('The statistics have changed now:')
pprint(ping.status)

Signal Tool¶

class photon.tools.signal.Signal(m, pid, sudo=True, cmdd_if_no_pid=None)[source]¶

The Signal tool can send signals to processes via kill, returning the results.

Parameters:	pid – Either the full path to the pidfile (e.g. `/var/run/proc.pid`) or the pid as number sudo – Prepend sudo before command. (Make sure to be root yourself if set to `False` or expect errors. Further for unattended operation add the user to `sudoers` file.)

_Signal__signal(sig, verbose=None)¶

Helper class preventing code duplication..

Parameters:	sig – Signal to use (e.g. “HUP”, “ALRM”) verbose – Overwrite `photon.Photon.m()`‘s verbose
Returns:	`photon.Photon.m()`‘s result of killing pid with specified pid

alrm¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGALRM

hup¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGHUP

int¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGINT with visible shell warning

kill¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGKILL with visible shell warning

quit¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGQUIT with visible shell warning

stop¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGSTOP with visible shell warning

usr1¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGUSR1

usr2¶

Returns:	`photon.Photon.m()`‘s result of killing pid using SIGUSR2

Template Tool¶

class photon.tools.template.Template(m, template, fields=None)[source]¶

The Template tool helps to process on strings.

Parameters:	template – The initial template to start with. If it’s value is recognized by `util.locations.search_location()` (a.k.a is a filename) the file contents will be loaded as template. Note If the file is not found, you will be doing string processing on the filename instead of the contents! fields – Initially set up fields. Can be done later, using `sub()`

The templating-language itself are normal Template strings, see there for syntax.

raw¶

Returns:	The raw template

sub¶

Parameters:	fields – Set fields to substitute
Returns:	Substituted Template with given fields. If no fields were set up beforehand, `raw()` is used.

write(filename, append=True, backup=True)[source]¶

Parameters:	filename – File to write into append – Either append to existing content (if not already included) or completely replace filename backup – Create a backup of filename before writing. Only applies when append is set

Tools¶

Git Tool¶

Mail Tool¶

Mail Tool Example¶

Ping Tool¶

Ping Tool Example¶

Signal Tool¶

Template Tool¶

Table Of Contents

Related Topics

This Page