Merge branch 'v0.6' into fabric_task_improvements

This commit is contained in:
coffeedogs 2018-06-27 10:41:11 +01:00 committed by coffeedogs
commit 7e2cb2176e
No known key found for this signature in database
GPG Key ID: 9D818C503D0B7E70
44 changed files with 3010 additions and 2645 deletions

4
.gitignore vendored
View File

@ -3,6 +3,7 @@
**.DS_Store
src/build
src/dist
src/.eggs
src/.project
src/.pydevproject
src/.settings/
@ -13,3 +14,6 @@ build/lib.*
build/temp.*
dist
*.egg-info
docs/_*/*
docs/autodoc/
pyan/

View File

@ -7,6 +7,5 @@ addons:
- build-essential
- libcap-dev
install:
- pip install -r requirements.txt
- python setup.py install
script: pybitmessage -t

View File

@ -1,15 +1,33 @@
## Code contributions to the Bitmessage project
## Repository contributions to the PyBitmessage project
- try to explain what the code is about
- try to follow [PEP0008](https://www.python.org/dev/peps/pep-0008/)
- make the pull request against the ["v0.6" branch](https://github.com/Bitmessage/PyBitmessage/tree/v0.6)
- PGP-sign the commits included in the pull request
- try to use a good editor that removes trailing whitespace, highlights potential python issues and uses unix line endings
- You can get paid for merged commits if you register at [Tip4Commit](https://tip4commit.com/github/Bitmessage/PyBitmessage)
If for some reason you don't want to use github, you can submit the patch using Bitmessage to the "bitmessage" chan, or to one of the developers.
### Code
- Try to refer to github issue tracker or other permanent sources of discussion about the issue.
- It is clear from the diff *what* you have done, it may be less clear *why* you have done it so explain why this change is necessary rather than what it does
### Documentation
- If there has been a change to the code, there's a good possibility there should be a corresponding change to the documentation
- If you can't run `fab build_docs` successfully, ask for someone to run it against your branch
### Tests
- If there has been a change to the code, there's a good possibility there should be a corresponding change to the tests
- If you can't run `fab tests` successfully, ask for someone to run it against your branch
## Translations
For helping with translations, please use [Transifex](https://www.transifex.com/bitmessage-project/pybitmessage/). There is no need to submit pull requests for translations.
For translating technical terms it is recommended to consult the [Microsoft Language Portal](https://www.microsoft.com/Language/en-US/Default.aspx).
- For helping with translations, please use [Transifex](https://www.transifex.com/bitmessage-project/pybitmessage/).
- There is no need to submit pull requests for translations.
- For translating technical terms it is recommended to consult the [Microsoft Language Portal](https://www.microsoft.com/Language/en-US/Default.aspx).
### Gitiquette
- Make the pull request against the ["v0.6" branch](https://github.com/Bitmessage/PyBitmessage/tree/v0.6)
- PGP-sign the commits included in the pull request
- Use references to tickets, e.g. `addresses #123` or `fixes #234` in your commit messages
- Try to use a good editor that removes trailing whitespace, highlights potential python issues and uses unix line endings
- If for some reason you don't want to use github, you can submit the patch using Bitmessage to the "bitmessage" chan, or to one of the developers.

203
checkdeps.py Normal file → Executable file
View File

@ -1,3 +1,4 @@
#!/usr/bin/env python2
"""
Check dependendies and give recommendations about how to satisfy them
@ -9,112 +10,24 @@ Limitations:
EXTRAS_REQUIRE. This is fine because most developers do, too.
"""
import os
from distutils.errors import CompileError
try:
from setuptools.dist import Distribution
from setuptools.extension import Extension
from setuptools.command.build_ext import build_ext
HAVE_SETUPTOOLS = True
# another import from setuptools is in setup.py
from setup import EXTRAS_REQUIRE
except ImportError:
HAVE_SETUPTOOLS = False
EXTRAS_REQUIRE = []
from importlib import import_module
import os
import sys
from setup import EXTRAS_REQUIRE
from src.depends import detectOS, PACKAGES, PACKAGE_MANAGER
PROJECT_ROOT = os.path.abspath('..')
sys.path.insert(0, PROJECT_ROOT)
# OS-specific dependencies for optional components listed in EXTRAS_REQUIRE
EXTRAS_REQUIRE_DEPS = {
# The values from setup.EXTRAS_REQUIRE
'python_prctl': {
# The packages needed for this requirement, by OS
"OpenBSD": [""],
"FreeBSD": [""],
"Debian": ["libcap-dev"],
"Ubuntu": [""],
"Ubuntu 12": [""],
"openSUSE": [""],
"Fedora": [""],
"Guix": [""],
"Gentoo": [""],
},
}
PACKAGE_MANAGER = {
"OpenBSD": "pkg_add",
"FreeBSD": "pkg install",
"Debian": "apt-get install",
"Ubuntu": "apt-get install",
"Ubuntu 12": "apt-get install",
"openSUSE": "zypper install",
"Fedora": "dnf install",
"Guix": "guix package -i",
"Gentoo": "emerge"
}
PACKAGES = {
"PyQt4": {
"OpenBSD": "py-qt4",
"FreeBSD": "py27-qt4",
"Debian": "python-qt4",
"Ubuntu": "python-qt4",
"Ubuntu 12": "python-qt4",
"openSUSE": "python-qt",
"Fedora": "PyQt4",
"Guix": "python2-pyqt@4.11.4",
"Gentoo": "dev-python/PyQt4",
'optional': True,
'description': "You only need PyQt if you want to use the GUI. " \
"When only running as a daemon, this can be skipped.\n" \
"However, you would have to install it manually " \
"because setuptools does not support PyQt."
},
"msgpack": {
"OpenBSD": "py-msgpack",
"FreeBSD": "py27-msgpack-python",
"Debian": "python-msgpack",
"Ubuntu": "python-msgpack",
"Ubuntu 12": "msgpack-python",
"openSUSE": "python-msgpack-python",
"Fedora": "python2-msgpack",
"Guix": "python2-msgpack",
"Gentoo": "dev-python/msgpack",
"optional": True,
"description": "python-msgpack is recommended for improved performance of message encoding/decoding"
},
"pyopencl": {
"FreeBSD": "py27-pyopencl",
"Debian": "python-pyopencl",
"Ubuntu": "python-pyopencl",
"Ubuntu 12": "python-pyopencl",
"Fedora": "python2-pyopencl",
"openSUSE": "",
"OpenBSD": "",
"Guix": "",
"Gentoo": "dev-python/pyopencl",
"optional": True,
'description': "If you install pyopencl, you will be able to use " \
"GPU acceleration for proof of work. \n" \
"You also need a compatible GPU and drivers."
},
"setuptools": {
"OpenBSD": "py-setuptools",
"FreeBSD": "py27-setuptools",
"Debian": "python-setuptools",
"Ubuntu": "python-setuptools",
"Ubuntu 12": "python-setuptools",
"Fedora": "python2-setuptools",
"openSUSE": "python-setuptools",
"Guix": "python2-setuptools",
"Gentoo": "",
"optional": False,
}
}
COMPILING = {
"Debian": "build-essential libssl-dev",
"Ubuntu": "build-essential libssl-dev",
@ -123,46 +36,23 @@ COMPILING = {
"optional": False,
}
def detectOSRelease():
with open("/etc/os-release", 'r') as osRelease:
version = None
for line in osRelease:
if line.startswith("NAME="):
line = line.lower()
if "fedora" in line:
detectOS.result = "Fedora"
elif "opensuse" in line:
detectOS.result = "openSUSE"
elif "ubuntu" in line:
detectOS.result = "Ubuntu"
elif "debian" in line:
detectOS.result = "Debian"
elif "gentoo" in line or "calculate" in line:
detectOS.result = "Gentoo"
else:
detectOS.result = None
if line.startswith("VERSION_ID="):
try:
version = float(line.split("=")[1].replace("\"", ""))
except ValueError:
pass
if detectOS.result == "Ubuntu" and version < 14:
detectOS.result = "Ubuntu 12"
# OS-specific dependencies for optional components listed in EXTRAS_REQUIRE
EXTRAS_REQUIRE_DEPS = {
# The values from setup.EXTRAS_REQUIRE
'python_prctl': {
# The packages needed for this requirement, by OS
"OpenBSD": [""],
"FreeBSD": [""],
"Debian": ["libcap-dev python-prctl"],
"Ubuntu": ["libcap-dev python-prctl"],
"Ubuntu 12": ["libcap-dev python-prctl"],
"openSUSE": [""],
"Fedora": ["prctl"],
"Guix": [""],
"Gentoo": ["dev-python/python-prctl"],
},
}
def detectOS():
if detectOS.result is not None:
return detectOS.result
if sys.platform.startswith('openbsd'):
detectOS.result = "OpenBSD"
elif sys.platform.startswith('freebsd'):
detectOS.result = "FreeBSD"
elif sys.platform.startswith('win'):
detectOS.result = "Windows"
elif os.path.isfile("/etc/os-release"):
detectOSRelease()
elif os.path.isfile("/etc/config.scm"):
detectOS.result = "Guix"
return detectOS.result
def detectPrereqs(missing=True):
available = []
@ -176,18 +66,21 @@ def detectPrereqs(missing=True):
available.append(module)
return available
def prereqToPackages():
if not detectPrereqs():
return
print "%s %s" % (
print("%s %s" % (
PACKAGE_MANAGER[detectOS()], " ".join(
PACKAGES[x][detectOS()] for x in detectPrereqs()))
PACKAGES[x][detectOS()] for x in detectPrereqs())))
def compilerToPackages():
if not detectOS() in COMPILING:
return
print "%s %s" % (
PACKAGE_MANAGER[detectOS.result], COMPILING[detectOS.result])
print("%s %s" % (
PACKAGE_MANAGER[detectOS.result], COMPILING[detectOS.result]))
def testCompiler():
if not HAVE_SETUPTOOLS:
@ -214,30 +107,30 @@ def testCompiler():
fullPath = os.path.join(cmd.build_lib, cmd.get_ext_filename("bitmsghash"))
return os.path.isfile(fullPath)
detectOS.result = None
prereqs = detectPrereqs()
prereqs = detectPrereqs()
compiler = testCompiler()
if (not compiler or prereqs) and detectOS() in PACKAGE_MANAGER:
print "It looks like you're using %s. " \
"It is highly recommended to use the package manager\n" \
"to install the missing dependencies." % (detectOS.result)
print(
"It looks like you're using %s. "
"It is highly recommended to use the package manager\n"
"to install the missing dependencies." % detectOS.result)
if not compiler:
print "Building the bitmsghash module failed.\n" \
"You may be missing a C++ compiler and/or the OpenSSL headers."
print(
"Building the bitmsghash module failed.\n"
"You may be missing a C++ compiler and/or the OpenSSL headers.")
if prereqs:
mandatory = list(x for x in prereqs if "optional" not in PACKAGES[x] or not PACKAGES[x]["optional"])
optional = list(x for x in prereqs if "optional" in PACKAGES[x] and PACKAGES[x]["optional"])
mandatory = [x for x in prereqs if not PACKAGES[x].get("optional")]
optional = [x for x in prereqs if PACKAGES[x].get("optional")]
if mandatory:
print "Missing mandatory dependencies: %s" % (" ".join(mandatory))
print("Missing mandatory dependencies: %s" % " ".join(mandatory))
if optional:
print "Missing optional dependencies: %s" % (" ".join(optional))
print("Missing optional dependencies: %s" % " ".join(optional))
for package in optional:
print PACKAGES[package].get('description')
print(PACKAGES[package].get('description'))
# Install the system dependencies of optional extras_require components
OPSYS = detectOS()
@ -259,12 +152,14 @@ for lhs, rhs in EXTRAS_REQUIRE.items():
if x in EXTRAS_REQUIRE_DEPS
]),
])
print "Optional dependency `pip install .[{}]` would require `{}` to be run as root".format(lhs, rhs_cmd)
print(
"Optional dependency `pip install .[{}]` would require `{}`"
" to be run as root".format(lhs, rhs_cmd))
if (not compiler or prereqs) and detectOS() in PACKAGE_MANAGER:
print "You can install the missing dependencies by running, as root:"
if (not compiler or prereqs) and OPSYS in PACKAGE_MANAGER:
print("You can install the missing dependencies by running, as root:")
if not compiler:
compilerToPackages()
prereqToPackages()
else:
print "All the dependencies satisfied, you can install PyBitmessage"
print("All the dependencies satisfied, you can install PyBitmessage")

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = PyBitmessage
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

210
docs/conf.py Normal file
View File

@ -0,0 +1,210 @@
# -*- coding: utf-8 -*-
"""
Configuration file for the Sphinx documentation builder.
This file does only contain a selection of the most common options. For a
full list see the documentation:
http://www.sphinx-doc.org/en/master/config
-- Path setup --------------------------------------------------------------
If extensions (or modules to document with autodoc) are in another directory,
add these directories to sys.path here. If the directory is relative to the
documentation root, use os.path.abspath to make it absolute, like shown here.
"""
import os
import sys
from sphinx.apidoc import main
from mock import Mock as MagicMock
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../src'))
sys.path.insert(0, os.path.abspath('../src/pyelliptic'))
import version
# -- Project information -----------------------------------------------------
project = u'PyBitmessage'
copyright = u'2018, The Bitmessage Team' # pylint: disable=redefined-builtin
author = u'The Bitmessage Team'
# The short X.Y version
version = unicode(version.softwareVersion)
# The full version, including alpha/beta/rc tags
release = version
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
# 'sphinx.ext.doctest', # Currently disabled due to bad doctests
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
'm2r',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# Deal with long lines in source view
html_theme_options = {
'page_width': '1366px',
}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'PyBitmessagedoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PyBitmessage.tex', u'PyBitmessage Documentation',
u'The Bitmessage Team', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pybitmessage', u'PyBitmessage Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PyBitmessage', u'PyBitmessage Documentation',
author, 'PyBitmessage', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

View File

@ -0,0 +1,18 @@
Documentation
=============
Sphinx is used to pull richly formatted comments out of code, merge them with hand-written documentation and render it
in HTML and other formats.
To build the docs, simply run `$ fab -H localhost build_docs` once you have set up Fabric.
Restructured Text (RsT) vs MarkDown (md)
----------------------------------------
There's much on the internet about this. Suffice to say RsT_ is preferred for Python documentation while md is preferred for web markup or for certain other languages.
.. _Rst: [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html]` style is preferred,
`md` files can also be incorporated by using mdinclude directives in the indices. They are translated to RsT before rendering to the various formats. Headers are translated as a hard-coded level `(H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #`. This represents a small consideration for both styles. If markup is not translated to rst well enough, switch to rst.

View File

@ -0,0 +1,2 @@
.. mdinclude:: fabfile/README.md

View File

@ -0,0 +1,38 @@
Operational Security
====================
Bitmessage has many features that are designed to protect your anonymity during normal use. There are other things that you must or should do if you value your anonymity.
Castles in the sand
-------------------
You cannot build a strong castle on unstable foundations. If your operating system is not wholly owned by you then it is impossible to make guarantees about an application.
* Carefully choose your operating system
* Ensure your operating system is up to date
* Ensure any dependencies and requirements are up to date
Extrordinary claims require extrordinary evidence
-------------------------------------------------
If we are to make bold claims about protecting your privacy we should demonstrate this by strong actions.
- PGP signed commits
- looking to audit
- warrant canary
Digital foootprint
------------------
Your internet use can reveal metadata you wouldn't expect. This can be connected with other information about you if you're not careful.
* Use separate addresses for different puprose
* Don't make the same mistakes all the time
* Your language use is unique. The more you type, the more you fingerprint yourself. The words you know and use often vs the words you don't know or use often.
Cleaning history
----------------
* Tell your browser not to store BitMessage addresses
* Microsoft Office seems to offer the ability to define sensitive informations types. If browsers don't already they may in the future. Consider adding `BM-\w{x..y}`.

View File

@ -0,0 +1,88 @@
Developing
==========
Devops tasks
------------
Bitmessage makes use of fabric_ to define tasks such as building documentation or running checks and tests on the code. If you can install
.. _fabric: https://fabfile.org
Code style and linters
----------------------
We aim to be PEP8 compliant but we recognise that we have a long way still to go. Currently we have style and lint exceptions specified at the most specific place we can. We are ignoring certain issues project-wide in order to avoid alert-blindess, avoid style and lint regressions and to allow continuous integration to hook into the output from the tools. While it is hoped that all new changes pass the checks, fixing some existing violations are mini-projects in themselves. Current thinking on ignorable violations is reflected in the options and comments in setup.cfg. Module and line-level lint warnings represent refactoring opportunities.
Pull requests
-------------
There is a template at PULL_REQUEST_TEMPLATE.md that appears in the pull-request description. Please replace this text with something appropriate to your changes based off the ideas in the template.
Bike-shedding
-------------
Beyond having well-documented, Pythonic code with static analysis tool checks, extensive test coverage and powerful devops tools, what else can we have? Without violating any linters there is room for making arbirary decisions solely for the sake of project consistency. These are the stuff of the pedant's PR comments. Rather than have such conversations in PR comments, we can lay out the result of discussion here.
I'm putting up a strawman for each topic here, mostly based on my memory of reading related Stack Overflow articles etc. If contributors feel strongly (and we don't have anything better to do) then maybe we can convince each other to update this section.
Trailing vs hanging braces
Data
Hanging closing brace is preferred, trailing commas always to help reduce churn in diffs
Function, class, method args
Inline until line-length, then style as per data
Nesting
Functions
Short: group hanging close parentheses
Long: one closing parentheses per line
Single vs double quotes
Single quotes are preferred; less strain on the hands, eyes
Double quotes are only better so as to contain single quotes, but we want to contain doubles as often
Line continuation
Implicit parentheses continuation is preferred
British vs American spelling
We should be consistent, it looks like we have American to British at approx 140 to 60 in the code. There's not enough occurrences that we couldn't be consistent one way or the other. It breaks my heart that British spelling could lose this one but I'm happy to 'z' things up for the sake of consistency. So I put forward British to be preferred. Either that strawman wins out, or I incite interest in ~bike-shedding~ guiding the direction of this crucial topic from others.
Dependency graph
----------------
These images are not very useful right now but the aim is to tweak the settings of one or more of them to be informative, and/or divide them up into smaller grapghs.
To re-build them, run `fab build_docs:dep_graphs=true`. Note that the dot graph takes a lot of time.
.. figure:: ../../../../_static/deps-neato.png
:alt: neato graph of dependencies
:width: 100 pc
:index:`Neato` graph of dependencies
.. figure:: ../../../../_static/deps-sfdp.png
:alt: SFDP graph of dependencies
:width: 100 pc
:index:`SFDP` graph of dependencies
.. figure:: ../../../../_static/deps-dot.png
:alt: Dot graph of dependencies
:width: 100 pc
:index:`Dot` graph of dependencies
Key management
--------------
Nitro key
^^^^^^^^^
Regular contributors are enouraged to take further steps to protect their key and the Nitro Key (Start) is recommended by the BitMessage project for this purpose.
Debian-quirks
~~~~~~~~~~~~~
Stretch makes use of the directory ~/.gnupg/private-keys-v1.d/ to store the private keys. This simplifies some steps of the Nitro Key instructions. See step 5 of Debian's subkeys_ wiki page
.. _subkeys: https://wiki.debian.org/Subkeys

View File

@ -0,0 +1,4 @@
Testing
=======
Currently there is a Travis job somewhere which runs python setup.py test. This doesn't find any tests when run locally for some reason.

View File

@ -0,0 +1,4 @@
TODO list
=========
.. todolist::

View File

@ -0,0 +1,8 @@
Developing
==========
.. toctree::
:maxdepth: 2
:glob:
develop.dir/*

View File

@ -0,0 +1,28 @@
Processes
=========
In other to keep the Bitmessage project running the team run a number of systems and accounts that form the
development pipeline and continuous delivery process. We are always striving to improve the process. Towards
that end it is documented here.
Project website
---------------
The bitmessage website_
Github
------
Our official Github_ account is Bitmessage. Our issue tracker is here as well.
BitMessage
----------
We eat our own dog food! You can send us bug reports via the Bitmessage chan at xxx
.. _website: https://bitmessage.org
.. _Github: https://github.com/Bitmessage/PyBitmessage

25
docs/contribute.rst Normal file
View File

@ -0,0 +1,25 @@
Contributing
============
.. toctree::
:maxdepth: 2
:glob:
contribute.dir/*
- Report_
- Develop_(develop)
- Translate_
- Donate_
- Fork the code and open a PR_ on github
- Search the `issue tracker` on github or open a new issue
- Send bug report to the chan
.. _Report: https://github.com/Bitmessage/PyBitmessage/issues
.. _Develop: https://github.com/Bitmessage/PyBitmessage
.. _Translate: https://www.transifex.com/bitmessage-project/pybitmessage/
.. _Donate: https://tip4commit.com/github/Bitmessage/PyBitmessage
.. _PR: https://github.com/Bitmessage/PyBitmessage/pulls
.. _`issue tracker`: https://github.com/Bitmessage/PyBitmessage/issues
contributing/*

15
docs/index.rst Normal file
View File

@ -0,0 +1,15 @@
.. mdinclude:: ../README.md
.. toctree::
:maxdepth: 2
overview
usage
contribute
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

36
docs/make.bat Normal file
View File

@ -0,0 +1,36 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
set SPHINXPROJ=PyBitmessage
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

21
docs/usage.rst Normal file
View File

@ -0,0 +1,21 @@
Usage
=====
GUI
---
Bitmessage has a PyQT GUI_
CLI
---
Bitmessage has a CLI_
API
---
Bitmessage has an XML-RPC API_
.. _GUI: https://bitmessage.org/wiki/PyBitmessage_Help
.. _CLI: https://bitmessage.org/wiki/PyBitmessage_Help
.. _API: https://bitmessage.org/wiki/API_Reference

View File

@ -85,3 +85,17 @@ Host github
HostName github.com
IdentityFile ~/.ssh/id_rsa_github
```
# Ideas for further development
## Smaller
* Decorators and context managers are useful for accepting common params like verbosity, force or doing command-level help
* if `git status` or `git status --staged` produce results, prefer that to generate the file list
## Larger
* Support documentation translations, aim for current transifex'ed languages
* Fabric 2 is finally out, go @bitprophet! Invoke/Fabric2 is a rewrite of Fabric supporting Python3. Probably makes
sense for us to stick to the battle-hardened 1.x branch, at least until we support Python3.

View File

@ -17,7 +17,7 @@ For more help on a particular command
from fabric.api import env
from fabfile.tasks import code_quality, test
from fabfile.tasks import code_quality, build_docs, push_docs, clean, test
# Without this, `fab -l` would display the whole docstring as preamble
@ -27,6 +27,9 @@ __doc__ = ""
__all__ = [
"code_quality",
"test",
"build_docs",
"push_docs",
"clean",
]
# Honour the user's ssh client configuration

View File

@ -1,12 +1,17 @@
# pylint: disable=not-context-manager
"""
Fabric tasks for PyBitmessage devops operations.
Note that where tasks declare params to be bools, they use coerce_bool() and so will accept any commandline (string)
representation of true or false that coerce_bool() understands.
"""
import os
import sys
from fabric.api import run, task, hide, cd
from fabric.api import run, task, hide, cd, settings, sudo
from fabric.contrib.project import rsync_project
from fabvenv import virtualenv
from fabfile.lib import (
@ -14,6 +19,9 @@ from fabfile.lib import (
get_filtered_pycodestyle_output, get_filtered_flake8_output, get_filtered_pylint_output,
)
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.dirname(__file__)), 'src'))) # noqa:E402
from version import softwareVersion # pylint: disable=wrong-import-position
def get_tool_results(file_list):
"""Take a list of files and resuln the results of applying the tools"""
@ -114,6 +122,43 @@ def generate_file_list(filename):
return file_list
def create_dependency_graphs():
"""
To better understand the relationship between methods, dependency graphs can be drawn between functions and
methods.
Since the resulting images are large and could be out of date on the next commit, storing them in the repo is
pointless. Instead, it makes sense to build a dependency graph for a particular, documented version of the code.
.. todo:: Consider saving a hash of the intermediate dotty file so unnecessary image generation can be avoided.
"""
with virtualenv(VENV_ROOT):
with hide('running', 'stdout'):
# .. todo:: consider a better place to put this, use a particular commit
with cd(PROJECT_ROOT):
with settings(warn_only=True):
if run('stat pyan').return_code:
run('git clone https://github.com/davidfraser/pyan.git')
with cd(os.path.join(PROJECT_ROOT, 'pyan')):
run('git checkout pre-python3')
# .. todo:: Use better settings. This is MVP to make a diagram
with cd(PROJECT_ROOT):
file_list = run("find . -type f -name '*.py' ! -path './src/.eggs/*'").split('\r\n')
for cmd in [
'neato -Goverlap=false -Tpng > deps-neato.png',
'sfdp -Goverlap=false -Tpng > deps-sfdp.png',
'dot -Goverlap=false -Tpng > deps-dot.png',
]:
pyan_cmd = './pyan/pyan.py {} --dot'.format(' '.join(file_list))
sed_cmd = r"sed s'/http\-old/http_old/'g" # dot doesn't like dashes
run('|'.join([pyan_cmd, sed_cmd, cmd]))
run('mv *.png docs/_build/html/_static/')
@task
@default_hosts(['localhost'])
def code_quality(verbose=True, details=False, fix=False, filename=None, top=10, rev=None):
@ -137,11 +182,9 @@ def code_quality(verbose=True, details=False, fix=False, filename=None, top=10,
:type details: bool, default False
:param fix: Run autopep8 aggressively on the displayed file(s)
:type fix: bool, default False
:param filename: Rather than analysing all files and displaying / fixing the top N, just analyse / display / fix
the specified file
:param filename: Don't test/fix the top N, just the specified file
:type filename: string, valid path to a file, default all files in the project
:return: This fabric task has an exit status equal to the total number of violations and uses stdio but it does
not return anything if you manage to call it successfully from Python
:return: None, exit status equals total number of violations
:rtype: None
Intended to be temporary until we have improved code quality and have safeguards to maintain it in place.
@ -180,3 +223,96 @@ def test():
run('pybitmessage -t')
run('python setup.py test')
@task
@default_hosts(['localhost'])
def build_docs(dep_graph=False, apidoc=True):
"""
Build the documentation locally.
:param dep_graph: Build the dependency graphs
:type dep_graph: Bool, default False
:param apidoc: Build the automatically generated rst files from the source code
:type apidoc: Bool, default True
Default usage:
$ fab -H localhost build_docs
Implementation:
First, a dependency graph is generated and converted into an image that is referenced in the development page.
Next, the sphinx-apidoc command is (usually) run which searches the code. As part of this it loads the modules and
if this has side-effects then they will be evident. Any documentation strings that make use of Python documentation
conventions (like parameter specification) or the Restructured Text (RsT) syntax will be extracted.
Next, the `make html` command is run to generate HTML output. Other formats (epub, pdf) are available.
.. todo:: support other languages
"""
apidoc = coerce_bool(apidoc)
if coerce_bool(dep_graph):
create_dependency_graphs()
with virtualenv(VENV_ROOT):
with hide('running'):
apidoc_result = 0
if apidoc:
run('mkdir -p {}'.format(os.path.join(PROJECT_ROOT, 'docs', 'autodoc')))
with cd(os.path.join(PROJECT_ROOT, 'docs', 'autodoc')):
with settings(warn_only=True):
run('rm *.rst')
with cd(os.path.join(PROJECT_ROOT, 'docs')):
apidoc_result = run('sphinx-apidoc -o autodoc ..').return_code
with cd(os.path.join(PROJECT_ROOT, 'docs')):
make_result = run('make html').return_code
return_code = apidoc_result + make_result
sys.exit(return_code)
@task
@default_hosts(['localhost'])
def push_docs(path=None):
"""
Upload the generated docs to a public server.
Default usage:
$ fab -H localhost push_docs
.. todo:: support other languages
.. todo:: integrate with configuration management data to get web root and webserver restart command
"""
# Making assumptions
WEB_ROOT = path if path is not None else os.path.join('var', 'www', 'html', 'pybitmessage', 'en', 'latest')
VERSION_ROOT = os.path.join(os.path.dirname(WEB_ROOT), softwareVersion)
rsync_project(
remote_dir=VERSION_ROOT,
local_dir=os.path.join(PROJECT_ROOT, 'docs', '_build', 'html')
)
result = run('ln -sf {0} {1}'.format(WEB_ROOT, VERSION_ROOT))
if result.return_code:
print 'Linking the new release failed'
# More assumptions
sudo('systemctl restart apache2')
@task
@default_hosts(['localhost'])
def clean():
"""Clean up files generated by fabric commands."""
with hide('running', 'stdout'):
with cd(PROJECT_ROOT):
run(r"find . -name '*.pyc' -exec rm '{}' \;")

View File

View File

@ -15,7 +15,14 @@ EXTRAS_REQUIRE = {
'pyopencl': ['pyopencl'],
'prctl': ['python_prctl'], # Named threads
'qrcode': ['qrcode'],
'sound;platform_system=="Windows"': ['winsound']
'sound;platform_system=="Windows"': ['winsound'],
'docs': [
'sphinx', # fab build_docs
'graphviz', # fab build_docs
'curses', # src/depends.py
'python2-pythondialog', # src/depends.py
'm2r', # fab build_docs
],
}

View File

@ -5,66 +5,68 @@ import xmlrpclib
import json
import time
api = xmlrpclib.ServerProxy("http://bradley:password@localhost:8442/")
if __name__ == '__main__':
print 'Let\'s test the API first.'
inputstr1 = "hello"
inputstr2 = "world"
print api.helloWorld(inputstr1, inputstr2)
print api.add(2,3)
api = xmlrpclib.ServerProxy("http://bradley:password@localhost:8442/")
print 'Let\'s set the status bar message.'
print api.statusBar("new status bar message")
print 'Let\'s test the API first.'
inputstr1 = "hello"
inputstr2 = "world"
print api.helloWorld(inputstr1, inputstr2)
print api.add(2,3)
print 'Let\'s list our addresses:'
print api.listAddresses()
print 'Let\'s set the status bar message.'
print api.statusBar("new status bar message")
print 'Let\'s list our address again, but this time let\'s parse the json data into a Python data structure:'
jsonAddresses = json.loads(api.listAddresses())
print jsonAddresses
print 'Now that we have our address data in a nice Python data structure, let\'s look at the first address (index 0) and print its label:'
print jsonAddresses['addresses'][0]['label']
print 'Let\'s list our addresses:'
print api.listAddresses()
print 'Uncomment the next two lines to create a new random address with a slightly higher difficulty setting than normal.'
#addressLabel = 'new address label'.encode('base64')
#print api.createRandomAddress(addressLabel,False,1.05,1.1111)
print 'Let\'s list our address again, but this time let\'s parse the json data into a Python data structure:'
jsonAddresses = json.loads(api.listAddresses())
print jsonAddresses
print 'Now that we have our address data in a nice Python data structure, let\'s look at the first address (index 0) and print its label:'
print jsonAddresses['addresses'][0]['label']
print 'Uncomment these next four lines to create new deterministic addresses.'
#passphrase = 'asdfasdfqwser'.encode('base64')
#jsonDeterministicAddresses = api.createDeterministicAddresses(passphrase, 2, 4, 1, False)
#print jsonDeterministicAddresses
#print json.loads(jsonDeterministicAddresses)
print 'Uncomment the next two lines to create a new random address with a slightly higher difficulty setting than normal.'
#addressLabel = 'new address label'.encode('base64')
#print api.createRandomAddress(addressLabel,False,1.05,1.1111)
#print 'Uncomment this next line to print the first deterministic address that would be generated with the given passphrase. This will Not add it to the Bitmessage interface or the keys.dat file.'
#print api.getDeterministicAddress('asdfasdfqwser'.encode('base64'),4,1)
print 'Uncomment these next four lines to create new deterministic addresses.'
#passphrase = 'asdfasdfqwser'.encode('base64')
#jsonDeterministicAddresses = api.createDeterministicAddresses(passphrase, 2, 4, 1, False)
#print jsonDeterministicAddresses
#print json.loads(jsonDeterministicAddresses)
#print 'Uncomment this line to subscribe to an address. (You must use your own address, this one is invalid).'
#print api.addSubscription('2D94G5d8yp237GGqAheoecBYpdehdT3dha','test sub'.encode('base64'))
#print 'Uncomment this next line to print the first deterministic address that would be generated with the given passphrase. This will Not add it to the Bitmessage interface or the keys.dat file.'
#print api.getDeterministicAddress('asdfasdfqwser'.encode('base64'),4,1)
#print 'Uncomment this line to unsubscribe from an address.'
#print api.deleteSubscription('2D94G5d8yp237GGqAheoecBYpdehdT3dha')
#print 'Uncomment this line to subscribe to an address. (You must use your own address, this one is invalid).'
#print api.addSubscription('2D94G5d8yp237GGqAheoecBYpdehdT3dha','test sub'.encode('base64'))
print 'Let\'s now print all of our inbox messages:'
print api.getAllInboxMessages()
inboxMessages = json.loads(api.getAllInboxMessages())
print inboxMessages
#print 'Uncomment this line to unsubscribe from an address.'
#print api.deleteSubscription('2D94G5d8yp237GGqAheoecBYpdehdT3dha')
print 'Uncomment this next line to decode the actual message data in the first message:'
#print inboxMessages['inboxMessages'][0]['message'].decode('base64')
print 'Let\'s now print all of our inbox messages:'
print api.getAllInboxMessages()
inboxMessages = json.loads(api.getAllInboxMessages())
print inboxMessages
print 'Uncomment this next line in the code to delete a message'
#print api.trashMessage('584e5826947242a82cb883c8b39ac4a14959f14c228c0fbe6399f73e2cba5b59')
print 'Uncomment this next line to decode the actual message data in the first message:'
#print inboxMessages['inboxMessages'][0]['message'].decode('base64')
print 'Uncomment these lines to send a message. The example addresses are invalid; you will have to put your own in.'
#subject = 'subject!'.encode('base64')
#message = 'Hello, this is the message'.encode('base64')
#ackData = api.sendMessage('BM-Gtsm7PUabZecs3qTeXbNPmqx3xtHCSXF', 'BM-2DCutnUZG16WiW3mdAm66jJUSCUv88xLgS', subject,message)
#print 'The ackData is:', ackData
#while True:
# time.sleep(2)
# print 'Current status:', api.getStatus(ackData)
print 'Uncomment this next line in the code to delete a message'
#print api.trashMessage('584e5826947242a82cb883c8b39ac4a14959f14c228c0fbe6399f73e2cba5b59')
print 'Uncomment these lines to send a broadcast. The example address is invalid; you will have to put your own in.'
#subject = 'subject within broadcast'.encode('base64')
#message = 'Hello, this is the message within a broadcast.'.encode('base64')
#print api.sendBroadcast('BM-onf6V1RELPgeNN6xw9yhpAiNiRexSRD4e', subject,message)
print 'Uncomment these lines to send a message. The example addresses are invalid; you will have to put your own in.'
#subject = 'subject!'.encode('base64')
#message = 'Hello, this is the message'.encode('base64')
#ackData = api.sendMessage('BM-Gtsm7PUabZecs3qTeXbNPmqx3xtHCSXF', 'BM-2DCutnUZG16WiW3mdAm66jJUSCUv88xLgS', subject,message)
#print 'The ackData is:', ackData
#while True:
# time.sleep(2)
# print 'Current status:', api.getStatus(ackData)
print 'Uncomment these lines to send a broadcast. The example address is invalid; you will have to put your own in.'
#subject = 'subject within broadcast'.encode('base64')
#message = 'Hello, this is the message within a broadcast.'.encode('base64')
#print api.sendBroadcast('BM-onf6V1RELPgeNN6xw9yhpAiNiRexSRD4e', subject,message)

View File

@ -51,8 +51,6 @@ from class_singleCleaner import singleCleaner
from class_objectProcessor import objectProcessor
from class_singleWorker import singleWorker
from class_addressGenerator import addressGenerator
from class_smtpDeliver import smtpDeliver
from class_smtpServer import smtpServer
from bmconfigparser import BMConfigParser
from inventory import Inventory
@ -245,6 +243,19 @@ class Main:
state.enableGUI = False # run without a UI
# is the application already running? If yes then exit.
if state.enableGUI and not state.curses and not depends.check_pyqt():
sys.exit(
'PyBitmessage requires PyQt unless you want'
' to run it as a daemon and interact with it'
' using the API. You can download PyQt from '
'http://www.riverbankcomputing.com/software/pyqt/download'
' or by searching Google for \'PyQt Download\'.'
' If you want to run in daemon mode, see '
'https://bitmessage.org/wiki/Daemon\n'
'You can also run PyBitmessage with'
' the new curses interface by providing'
' \'-c\' as a commandline argument.'
)
shared.thisapp = singleinstance("", daemon)
if daemon and not state.testmode:
@ -297,12 +308,14 @@ class Main:
# SMTP delivery thread
if daemon and BMConfigParser().safeGet(
"bitmessagesettings", "smtpdeliver", '') != '':
from class_smtpDeliver import smtpDeliver
smtpDeliveryThread = smtpDeliver()
smtpDeliveryThread.start()
# SMTP daemon thread
if daemon and BMConfigParser().safeGetBoolean(
"bitmessagesettings", "smtpd"):
from class_smtpServer import smtpServer
smtpServerThread = smtpServer()
smtpServerThread.start()
@ -381,26 +394,14 @@ class Main:
BMConfigParser().remove_option('bitmessagesettings', 'dontconnect')
elif daemon is False:
if state.curses:
# if depends.check_curses():
if not depends.check_curses():
sys.exit()
print('Running with curses')
import bitmessagecurses
bitmessagecurses.runwrapper()
elif depends.check_pyqt():
else:
import bitmessageqt
bitmessageqt.run()
else:
sys.exit(
'PyBitmessage requires PyQt unless you want'
' to run it as a daemon and interact with it'
' using the API. You can download PyQt from '
'http://www.riverbankcomputing.com/software/pyqt/download'
' or by searching Google for \'PyQt Download\'.'
' If you want to run in daemon mode, see '
'https://bitmessage.org/wiki/Daemon\n'
'You can also run PyBitmessage with'
' the new curses interface by providing'
' \'-c\' as a commandline argument.'
)
if daemon:
if state.testmode:

View File

@ -1,9 +1,5 @@
# pylint: disable=too-many-lines,broad-except,too-many-instance-attributes,global-statement,too-few-public-methods
# pylint: disable=too-many-statements,too-many-branches,attribute-defined-outside-init,too-many-arguments,no-member
# pylint: disable=unused-argument,no-self-use,too-many-locals,unused-variable,too-many-nested-blocks
# pylint: disable=too-many-return-statements,protected-access,super-init-not-called,non-parent-init-called
"""
Initialise the QT interface
PyQt based UI for bitmessage, the main module
"""
import hashlib
@ -15,64 +11,51 @@ import sys
import textwrap
import time
from datetime import datetime, timedelta
from sqlite3 import register_adapter
from PyQt4 import QtCore, QtGui
from PyQt4.QtNetwork import QLocalSocket, QLocalServer
import debug
from debug import logger
try:
from PyQt4 import QtCore, QtGui
from PyQt4.QtNetwork import QLocalSocket, QLocalServer
except ImportError:
logmsg = (
'PyBitmessage requires PyQt unless you want to run it as a daemon and interact with it using the API. You can'
' download it from http://www.riverbankcomputing.com/software/pyqt/download or by searching Google for '
'\'PyQt Download\' (without quotes).'
)
logger.critical(logmsg, exc_info=True)
sys.exit()
from sqlite3 import register_adapter # pylint: disable=wrong-import-order
from tr import _translate
from addresses import decodeAddress, addBMIfNotPresent
import shared
from bitmessageui import Ui_MainWindow
from bmconfigparser import BMConfigParser
import defaults
from namecoin import namecoinConnection
from messageview import MessageView
from migrationwizard import Ui_MigrationWizard
from foldertree import (
AccountMixin, Ui_FolderWidget, Ui_AddressWidget, Ui_SubscriptionWidget,
MessageList_AddressWidget, MessageList_SubjectWidget,
Ui_AddressBookWidgetItemLabel, Ui_AddressBookWidgetItemAddress)
from settings import Ui_settingsDialog
import settingsmixin
import support
import debug
from helper_ackPayload import genAckPayload
from helper_sql import sqlQuery, sqlExecute, sqlExecuteChunked, sqlStoredProcedure
import helper_search
import knownnodes
import l10n
import openclpow
from utils import str_broadcast_subscribers, avatarize
from account import (
getSortedAccounts, getSortedSubscriptions, accountClass, BMAccount,
GatewayAccount, MailchuckAccount, AccountColor)
import dialogs
from helper_generic import powQueueSize
from network.stats import pendingDownload, pendingUpload
from uisignaler import UISignaler
import knownnodes
import paths
from proofofwork import getPowType
import queues
import shared
import shutdown
import state
import upnp
from bitmessageqt import sound, support, dialogs
from bitmessageqt.foldertree import (
AccountMixin, Ui_FolderWidget, Ui_AddressWidget, Ui_SubscriptionWidget, MessageList_AddressWidget,
MessageList_SubjectWidget, Ui_AddressBookWidgetItemLabel, Ui_AddressBookWidgetItemAddress,
)