Differences

This shows you the differences between two versions of the page.

--- navierstokes [2016/04/16 16:52] – [Download Latest Release] sekula
+++ navierstokes [2019/01/19 23:02] (current) – removed admin
@@ Line 1: / Line 1: @@
-====== NavierStokes ======
-{{ :navierstokeslogo.png?300|}}
-NavierStokes is a set of Python classes that allow you to bridge between social network accounts. These classes rely on a number of external tools to do the hard work of actually talking to networks. There is a master "executable" file that uses the supporting classes to bridge between your various accounts. See usage information below.
-It employs "fuzzy text matching", as well as a record of posts that have already been shared between networks, to try to prevent a post from being shared more than once to other networks (or back to the originating network). Fuzzy text matching is needed because different social networks encode or format the same information slightly differently. For instance, a post in HTML on Pump.io will not be formatted in HTML on Twitter, and Twitter will shorten links, thus altering the text of the original post. Fuzzy text matching uses statistical methods to attempt to compute the probability that the message has already been shared on a network. Above a match threshold, the post will not be shared.
-NavierStokes considers only posts made in the last hour when it scans the streams from different social networks. It won't re-post something that is 6 hours or 6 days old.
-===== License =====
-Copyright 2014, Stephen Jacob Sekula [[https://hub.polari.us/steve]]
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
-[[http://www.apache.org/licenses/LICENSE-2.0]]
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-===== Download Latest Release =====
-<code>
-git clone https://hub.polari.us/code/index.cgi/navierstokes/
-git checkout v1.0.1
-</code>
-Release notes:
-  * Removed Facebook support - fbcmd is an abandoned project and there is no suitable replacement that speaks to the current FB API. If you want to push to FB, I recommend using a bridge from another social network, like the one from Twitter to FB (and vice versa).
-  * The Message Object now supports a link back to the original post on the web (e.g. a URL pointing to the pump.io web object corresponding to the original note, or a URL pointing to the RSS news story turned into a message).
-  * SocialHandlers now support a "noshare_keyword" in the .cfg file. If this keyword is found in a post, that post will never be shared to other social networks. This lets you post without having NavierStokes share something to another network.
-  * Twitter now will post all messages shared to it, even those with >140 characters. Message content is truncated, depending on whether there is an attached image or not, and a link to the original message is embedded in the tweet. This will also help "spread the word" about the existence of alternative social networks by linking back to them.
-  * Twitter images are now no longer just t.co links inside a tweet; the image HTML and content itself is downloaded and processed, the image is rescued from the original tweet, and physically attached to messages posted to other social networks.
-  * Improved unicode handling in messages for Python 2.7.X, which is still the basic Python supported by this code.
-  * BUGFIXES: handle missing message object attributes in a more robust way; improved use of subprocess for running and checking the success of commands like "t"; avoid posting empty messages; lots of bugfixes for FacebookTools, but since it's gone now anyway... who cares?
-  * Email any bugs you find to <navierstokes+NOSPAM@polari.us>
-Browse the code: [[https://hub.polari.us/code/index.cgi/navierstokes/]]
-----
-===== Requirements =====
-  * cliaspora-0.1.9.tgz (Diaspora access) ([[https://freeshell.de/~mk/projects/cliaspora.html]])
-  * PyPump 0.5 (pump.io access)
-     * git clone https://github.com/xray7224/PyPump.git
-     * cd PyPump
-     * git fetch
-     * git checkout v0.5
-  * cURL (GNU Social access)
-  * LYNX (for converting HTML to plain text - some social networks don't understand HTML)
-  * FuzzyWuzzy Python fuzzy text-matching libraries
-    * [[https://github.com/seatgeek/fuzzywuzzy]]
-    * git clone https://github.com/seatgeek/fuzzywuzzy.git
-    * cd fuzzywuzzy
-    * python setup.py install
-  * t (Ruby Gem for interacting with Twitter)
-    * This is needed if you want to bridge to Twitter.
-    * [[http://rubygems.org/gems/t]]
-    * gem install t (requires Ruby 1.9 or greater)
-  * txt2html: needed for clean text -> HTML conversion (e.g. from Twitter messages to Pump.io)
-  * ImageMagick: needed to rescale image attachments
-In general, here are the Python libraries needed to make this package operate:
-<code>
-abc
-calendar
-codecs
-commands
-copy
-feedparser
-fuzzywuzzy
-getopt
-hashlib
-inspect
-lockfile
-logging
-math
-os
-pycurl
-pypump
-re
-requests
-subprocess
-sys
-time
-unicodedata
-xml.dom.minidom
-</code>
-===== Installation =====
-  - Check out the code from the git repository above. This automatically creates the navierstokes/ directory.
-  - You should create a configuration file for NavierStokes: ~/.navierstokes/navierstokes.cfg. The syntax for the file is explained below.
-  - If you intend to bridge between Pump.io and other networks, you must use PyPump to register a client (e.g. NavierStokesApp) on Pump.io. Follow their instructions for getting the client credentials and tokens. Enter those into the <code>~/.navierstokes/navierstokes.cfg</code> file (see example below). PyPump docs: [[https://pypump.readthedocs.org/en/latest/]]
-  - Make sure Cliaspora is available in the PATH environment variable, or Diaspora interactions will fail.
-===== Example navierstokes.cfg file =====
-Be sure to make this .cfg file only readable by you:
-> chmod 600 ~/.navierstokes/navierstokes.cfg
-<code>
-[gnusocial]
-type: gnusocial
-site: https://gnusocial.server.url
-username: myname
-password: XXXXXXXXXXXXXXXX
-sharelevel: Public
-[pump.io]
-type: pump.io
-webfinger: user@pump.server
-client_credentials: XXXXXXXXXXXXXXXXXXXXxx
-client_tokens: XXXXXXXXXXXXXXXXXX
-sharelevel: All
-noshare_keyword: noshare
-[diaspora]
-type: diaspora
-webfinger: user@diaspora.server
-password: XXXXXXXXXXXXXXXXXXX
-aspect: public
-sharelevel: All
-noshare_keyword: diaspiverse
-[twitter]
-type: twitter
-sharelevel: Public
-shortenurls: True
-[my blog rss feed]
-type: rss
-feed_url: http://my.blog.example.com/rss/
-max_message_age: 84600
-[urlshortening]
-service: shortenizer
-serviceURL: http://u.jrobb.org
-serviceKey: pseudosecretKey
-#service: ur1
-#serviceURL: http://ur1.ca
-#serviceKey: False
-</code>
-Note that "sharelevel" means at what level of publicity from other networks you want a notice shared to this one. I've set this, for now, the way I like it. If you set this to "Public", ONLY notices that are public on other networks will go there. For instance, I only like to share things that are public on pump.io with Twitter. Things on Twitter are public by default, so they will ALWAYS be shared with other networks.
-"shortenurls" presently enabled will take ALL URLs listed in the message text and shorten them via ur1.ca. In the future, this will be a choice the user can make.
-"max_message_age" defines the maximum age, in seconds, that a post can be before it is no longer considered for sharing. This is best used for RSS feeds where articles added to the feed may be older than the time at which they are added to the feed (e.g. sharing news articles in a reading list). This defaults to 3600.
-The URL shortening section allows you to define a custom URL shortener. If unspecified, the default (presently, ur1.ca) is used.
-===== Running NavierStokes =====
-Once you have written a .cfg file and setup account information in it (and, in the case of Pump.io and Twitter, authenticated PyPump and t against those respective networks as clients), you can try executing NavierStokes manually:
-> python ./NavierStokes.py
-If you get errors, try running in Debug Mode and see what you can learn:
-> python ./NavierStokes.py -d
-I run NavierStokes every 5 minutes using a CRON job:
-<code>
-*/5 * * * * bash -l -c 'python /path/to/navierstokes/NavierStokes.py >> ${HOME}/.navierstokes/navierstokes.log 2>&1'
-</code>
-If you get any errors that are unrelated to passwords, logging into, report them to <navierstokes+NOSPAM@hub.polari.us>.
-===== A simple program to authenticate PyPump against your pump.io instance =====
-For PyPump v0.5, this ought to work:
-<code>
-#!/usr/bin/env python
-from pypump import PyPump, Client
-client = Client(
-    webfinger="ME@MY.PUMP",
-    type="native", # Can be "native" or "web"
-    name="NavierStokesApp"
-)
-def simple_verifier(url):
-    print 'Go to: ' + url
-    return raw_input('Verifier: ') # they will get a code back
-pump = PyPump(client=client, verifier_callback=simple_verifier)
-client_credentials = pump.get_registration() # will return [<key>, <secret>, <expirey>]
-client_tokens = pump.get_token() # [<token>, <secret>]
-print "client_credentials: %s,%s" % (client_credentials[0],client_credentials[1])
-print "client_tokens: %s,%s" % (client_tokens[0],client_tokens[1])
-</code>
-===== Bugs and Features =====
-  * [[community:NavierStokesBugTracker]]
-===== Roadmap =====
-Since v0.5.0, it's become clear to me what the roadmap for this software is going to be.
-  * Releases until we hit 0.9.0 are all to be considered "alpha" - try at your own risk, don't expect it to work, and please, please, please report bugs
-  * Releases in v0.9.X will be the "beta" - considered to have been exercised enough and by enough people, with features added and bugs squashed as a result. The final feature set needed to bridge your posts from one network to another will be locked in during this period.
-  * Releases in v1.X.X will be the stable versions resulting from the beta period
-  * The goal for v2.X.X is a bit ambitious - maybe even unnecessary - but that would be to bridge conversations that result from your posts shared across networks. At the very least, people should know that an interesting conversation is resulting on another network.
-I would be happy to just coast on v1.X.X until the federated networks implement APIs that allow automatic bridging (e.g. if GNU Social implements the pump.io API, it likely won't be necessary to bridge anymore with NavierStokes).
-===== Other Information =====
-  * The logo is a mashup of a Wikimedia Commons image from the Navier-Stokes Equation Wikipedia Page and the logo of the Pump.io, GNU Social, and Diaspora networks. I intentionally left Twitter off the logo as I don't want to deal with issues of using their logo.
-  * Bernoulli Fluid Flow image: "BernoullisLawDerivationDiagram" by MannyMax (original) - [[:Image:BernoullisLahenrique gostoso da america latia .,.... wDerivationDiagram.png]]. Licensed under Creative Commons Attribution-Share Alike 3.0 via Wikimedia Commons - https://commons.wikimedia.org/wiki/File:BernoullisLawDerivationDiagram.svg#mediaviewer/File:BernoullisLawDerivationDiagram.svg
-  * Pump.io logo: "Pump.io" by Mathiasgebbe - Own work. Licensed under Creative Commons Attribution-Share Alike 3.0 via Wikimedia Commons - http://commons.wikimedia.org/wiki/File:Pump.io.svg#mediaviewer/File:Pump.io.svg
-  * GNU Social Logo: http://gnu.org
-  * Diaspora Logo: "Diaspora social network project official logo, helvetica font". Via Wikipedia - https://en.wikipedia.org/wiki/File:Diaspora_social_network_project_official_logo,_helvetica_font.png#mediaviewer/File:Diaspora_social_network_project_official_logo,_helvetica_font.png
-  * WTF is this thing called "NavierStokes"?
-    * Well, I am a physicist. That's reason number one. Reason number two is that the "Navier-Stokes Equations" are a set of equations that exactly describe all fluid flow, including gases. In principle, they exactly describe the behavior of the motion of fluids from place to place (accounting for variables like pressure, velocity, stress, etc.). However, these equations are not always exactly, analytically solvable. So one has to solve the problem of fluid flow in specific situations and try to generalize the solution. Similarly, NavierStokes (the software bridge) is an attempt to solve the first problem of participating in multiple social networks: sending your messages to and from all the networks. It's not a perfect, exact, analytical solution to bridging social networks . . . but it's a start.