snose

Creative Commons Legal Code

CC0 1.0 Universal

    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
    HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.

For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:

  i. the right to reproduce, adapt, distribute, perform, display,
     communicate, and translate a Work;
 ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
     likeness depicted in a Work;
 iv. rights protecting against unfair competition in regards to a Work,
     subject to the limitations in paragraph 4(a), below;
  v. rights protecting the extraction, dissemination, use and reuse of data
     in a Work;
 vi. database rights (such as those arising under Directive 96/9/EC of the
     European Parliament and of the Council of 11 March 1996 on the legal
     protection of databases, and under any national implementation
     thereof, including any amended or successor version of such
     directive); and
vii. other similar, equivalent or corresponding rights throughout the
     world based on applicable law or treaty, and any national
     implementations thereof.


2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.

4. Limitations and Disclaimers.

 a. No trademark or patent rights held by Affirmer are waived, abandoned,
    surrendered, licensed or otherwise affected by this document.
 b. Affirmer offers the Work as-is and makes no representations or
    warranties of any kind concerning the Work, express, implied,
    statutory or otherwise, including without limitation warranties of
    title, merchantability, fitness for a particular purpose, non
    infringement, or the absence of latent or other defects, accuracy, or
    the present or absence of errors, whether or not discoverable, all to
    the greatest extent permissible under applicable law.
 c. Affirmer disclaims responsibility for clearing rights of other persons
    that may apply to the Work or any use thereof, including without
    limitation any person's Copyright and Related Rights in the Work.
    Further, Affirmer disclaims responsibility for obtaining any necessary
    consents, permissions or other rights required for any use of the
    Work.
 d. Affirmer understands and acknowledges that Creative Commons is not a
    party to this document and has no duty or obligation with respect to
    this CC0 or use of the Work.

#SNose - Simplenote Object Synchronisation (Explicit)

A command line client / python script using the [Simplenote.py](https://github.com/mrtazz/simplenote.py) module from [mrtazz (Daniel Schauenberg)](https://github.com/mrtazz) that allows you to synchronise just the (text) files you specify within a directory across multiple machines.

##FAQ

1. You thought of the name "snose" first and then tried to wangle in something to make it an acronym, didn't you? *Yes.*


##Inspiration

Basically I wanted a way to synchronise arbitrary "dotfiles" without the "expense" of a Git repository:

- Git seems a bit overkill
- I'm not really bothered about versioning, just synchronisation
- I just want to synchronise *some* files within a directory, not all of them (just imagine the `.gitignore`!)

##How to use



###In general - Authentication

Probably the best way is to store your credentials in `.netrc` with a `machine` of host "simple-note.appspot.com" and using the `login` and `password` entries. But you can also provide the username and password on the command line like so:

    python snose.py --username=me@email.com --password=mypassword

A token based approach would be nice, but for that I'd need to modify simplenote.py.

###Snort - Importing a new file

Take a file from the current directory and import into Simplenote as a new note:

    python snose.py --username=<me@email.com> --password=<mypassword> --snort=<filename.ext>
    
Note that snose works with with files in subdirectories as well, etc. The only issue I could see there would be cross-platform. I.e. path differences between Windows and \*Nix.

###Sniff - Importing an existing file

Take a file from the current directory and "match" it to an existing note within Simplenote

    python snose.py  --username=<me@email.com> --password=<mypassword> --sniff=<key> <filename.ext>

Where key is the id used by Simplenote to identify the note. So the best way to find this is to make sure the noted is tagged as "snose" in Simplenote and then you can use `snose.py --snot` to find the key.

###Sneeze - Export an existing file

Export a file from Simplenote to the current directory.

    python snose.py  --username=<me@email.com> --password=<mypassword> --sneeze=<key> <filename.ext>







###Sync - Synchronise files

Reads files in the `.snose` index file and synchronises them with Simplenote. 
    
	python snose.py  --username=<me@email.com> --password=<mypassword> --sync

You can pass the optional `--hanky` flag at the same time to perform a dry run; although the dry run can't indicate when merging will occur, only the ultimate direction of the update.

    python snose.py  --username=<me@email.com> --password=<mypassword> --sync --hanky


###Snot - List files available for synchronisation with SNose

Lists all files on Simplenote tagged "snose":

    python snose.py  --username=<me@email.com> --password=<mypassword> --snot

I could do with making this also list what is currently being synchronised based on the index. To make this most useful I suggest including the name of the file as a comment in the first line of the file. 

###Blow - Rollback to the previous version of a note

(Yeah, the command names are getting a bit rubbish now)

Rolls back a note both locally and remotely to the previous version. 

    python snose.py --username=<me@email.com> --password=<mypassword> --blow=<key>

The `blow` command requires Simplenote.py to be at [this commit](https://github.com/mrtazz/simplenote.py/commit/50e3de947b70fa5d9a7faee004ae20b169a1547d) at least.

	
##How it works

It's really quite simple (after all, I've done it), basically it creates a `.snose` file in the current directory that is json formatted. This is basically a Python dictionary that maps a filename (from the current directory) to a simplenote note (via the key) and also includes other simplenote data such as the modification date, version number and sync number (so it can figure out how to sync).

It then just implements the Simplenote recommendation from the api:

1. Iterates through each file stored in the `.snose` index.
2. First of all looks for local modifications (compares modification date of the file with what is stored in the index). 
3. Then attempts to update the remote version on Simplenote, but will merge the content if the remote has also changed. If merging occurs both the local and remote are updated.
4. Then checks for remote updates by comparing version numbers and updates local copies if necessary.


##To Do

- <s>Files in subdirectories, what happens there? I've just assumed all files in same directory as index</s> They work just fine! However, robust cross-platform support would be nice to handle/interpret file path differences between platforms.
- Using tags to contain filename: "filename:pants.txt" Some potential character limitations though? But an interesting idea for meta data.
- Add ability to "snort" multiple files"
- List files currently being synchronised (read the .snose index). The `--snot` lists files tagged *snose* on Simplenote and the two might not necessarily be the same (i.e you've chose to sync some files on one machine and a different set on another).
- Write updated index file once after sync, instead of writing for each file change (although writing per file does have it's advantage from an error handling point of view)
 

#!/usr/bin/python
#snose - Simplenote Object Synchronisation (Explicit)

import simplejson as json

from simplenote import Simplenote #Need to install this
import os.path, time
from optparse import OptionParser
import netrc


def main():
	parser = OptionParser()
	parser.add_option("--snort", action="store", type="string", help="Import a new file SNORT to Simplenote")
	parser.add_option("--sniff", action="store", nargs=2, type="string", help="Link a file with an already existing note in  Simplenote", metavar="<key> <filename>")
	parser.add_option("--sneeze", action="store", nargs=2, type="string", help="Export an existing file from Simplenote", metavar="<key> <filename>")
	parser.add_option("--blow", action="store", type="string", help="Roll back note of key BLOW to previous version")
	parser.add_option("--sync", help="Sync files in index", default=False, action='store_true')
	parser.add_option("--hanky", help="Use with --sync to perform a dry run", default=False, action='store_true')
	parser.add_option("--snot", help="List notes available for export (tagged snose)", default=False, action='store_true')

	parser.add_option("--username", action="store", type="string", help="Your Simplenote email address")
	parser.add_option("--password", action="store", type="string", help="Your Simplenote password")
	(options, args) = parser.parse_args()

	if not options.username or not options.password:
		#Check to see if stored somewhere
		try:
			options.username = netrc.netrc().authenticators("simple-note.appspot.com")[0]
			options.password = netrc.netrc().authenticators("simple-note.appspot.com")[2]
		except IOError as e:
			print 'Username and password must be supplied or exist .netrc file under domain of simple-note.appspot.com'
			exit()
	snclient = Simplenote(options.username, options.password)
	if options.snort:



		snort(snclient, options.snort)
	elif options.sniff:



		sniff(snclient, options.sniff[0], options.sniff[1])
	elif options.sneeze:
		sneeze(snclient, options.sneeze[0], options.sneeze[1])
	elif options.blow:
		blow(snclient, options.blow)
	elif options.snot:
		snot(snclient)
	elif options.sync and options.hanky:
		sync(snclient, True)
	elif options.sync:
		sync(snclient)
	else:
		print 'No options supplied'


def snort(snclient,filename): 
	# Add a new mapping, is actually add a new file
	try: #http://stackoverflow.com/questions/82831/how-do-i-check-if-a-file-exists-using-python#85237
		with open('.snose', 'r') as f:
			snose = json.load(f)
	except IOError as e:
		#Doesn't exist so create new
		snose = {}
	#Add new file to Simplenote
	#Need to get file contents
	try:
		with open(filename, 'r') as f:
			content = f.read()
	except IOError as e:
		print "Failed to read file %s" % filename
	else:
		try:
			returned = snclient.add_note({"content": content, "tags": ["snose"]})
			print "Imported %s into Simplenote with key %s" % (filename, returned[0]['key'])
		except IOError as e:
			print "Failed to add note to Simplenote"
			print e
		else:
			#Add mapping
			snose[filename] = {'key': returned[0]['key'], 'syncnum': returned[0]['syncnum'], 'version': returned[0]['version'], 'modifydate': float(os.path.getmtime(filename)) } #Use actual file mod date
			try:
				#Write back out
				with open('.snose', 'w') as f:

					json.dump(snose, f, indent=2)
			except IOError as e:
				print "Failed to update .snose index file"
				#But note was added to Simplenote so?
				print "But note was successfully imported to Simplenote with key %s. Try sniffing the file" % returned[0]['key']


def sniff(snclient,key, filename): #How to ensure remote gets or has snose tag?
	# Add a new mapping only
	try:
		with open('.snose', 'r') as f:
			snose = json.load(f)
	except IOError as e:
		#Assuming doesn't exist so create new
		snose = {}
	#Get details about current Simplenote file
	try:
		remote = snclient.get_note(key)
		#What if can't be found, need to abort...
	except IOError as e:
		print "Failed to find that note on Simplenote"
		print e
	else:
		try:
			#Add mapping
			snose[filename] = {'key': remote[0]['key'], 'syncnum': remote[0]['syncnum'], 'version': remote[0]['version'], 'modifydate': float(os.path.getmtime(filename)) }
			#Write back out
			with open('.snose', 'w') as f:
				json.dump(snose, f, indent=2)
		except IOError as e:
			print "Failed to update .snose index file"
			#Don't need to do anything else)


def sneeze(snclient, key, filename):
	#place an existing note in current directory
	try:
		with open('.snose', 'r') as f:
			snose = json.load(f)
	except IOError as e:
		#Doesn't exist so create new
		snose = {}
	#Get remote note
	try:
		remote = snclient.get_note(key)	
	except IOerror as e:
		print "Failed to find that note on Simplenote"
		print e
	else:
		#Write file




		try: 
			with open(filename, 'w') as f:
				f.write(remote[0]['content'])
		except IOError as e:
			print "Failed to create local copy of that note"
			print e

		else:






			#Update index
			try:
				snose[filename] = {'key': remote[0]['key'], 'syncnum': remote[0]['syncnum'], 'version': remote[0]['version'], 'modifydate': float(os.path.getmtime(filename)) } #Need to set as local modified date as otherwise will want to sync it straight away.
				#Write back out
				with open('.snose', 'w') as f:
					json.dump(snose, f, indent=2)
			except IOError as e:
				 print "Failed to update .snose index file"
				 print "But note was created locally. Try sniffing the file to add it to the index."


def blow(snclient, key):
	#With given key from .snose file, roll back to the previous version

	#1) Check exists in .snose index
	#2) Get previous version of remote
	#3) Write it out locally
	#4) Use that to update remote
	#5) Update index file with results

	#1) Check exists in .snose index
	try:
		with open('.snose', 'r') as f:
			snose = json.load(f)
		#Need to get filename of note, loop through, performance should be fine as .snose likely to be small

		filename = [name for name, local in snose.iteritems() if local['key'] == key][0]

		print "Attempting to rollback file %s" % filename
	except IOError as e:
		print "Note doesn't exist in local .snose index"
	else:
		#2) Get previous version of remote
		try:
			#fetch once to know version
			remote = snclient.get_note(key)
			rollback = snclient.get_note(key, remote[0]['version']-1)
		except IOError as e:
			print "Failed to fetch previous version"
		else:
			try: 
				#3) Write it out locally
				with open(filename, 'w') as f:
					f.write(rollback[0]['content'])
				print "Rolled back local copy"
			except IOError as e:

				print "Failed to rollback local copy of that note"
				print e
			else:
				#Since rollback doesn't include full meta data, update remote accordingly
				try:
					del remote[0]['syncnum']
					del remote[0]['version']
				except KeyError:
					pass
				finally:
					#Set modified date
					sysmodifydate = float(os.path.getmtime(filename))
					remote[0]['modifydate'] = sysmodifydate
					remote[0]['content'] = rollback[0]['content']
					#4) Use that to update remote
					try:
						returned = snclient.update_note(remote[0])
						print "Rolled back remote version"
					except IOError as e:
						print "Failed to roll back remote version"
					else:
						#Get returned metadata
						snose[filename]['syncnum'] = returned[0]['syncnum']
						snose[filename]['version'] = returned[0]['version']
						snose[filename]['modifydate'] = sysmodifydate
						try:
							#5) Update index file with results
							with open('.snose', 'w') as f:
								json.dump(snose, f, indent=2)
						except IOError as e:
							 print "Failed to update .snose index file"
							 print "Try running a sync to get index corrected."


def snot(snclient):
	#List simplenote notes tagged with "snose"
	notelist = snclient.get_note_list()
	#That gets list of keys. Then need to iterate through and get first line of text.
	#This is going to be slow.
	print "Key:                               \tNote"
	for note in notelist[0]:
		if ("snose" in note['tags']) & (int(note['deleted']) != 1):
			#get note itself
			remote = snclient.get_note(note['key'])
			print remote[0]['key']  + " \t" + remote[0]['content'].splitlines()[0]


def sync(snclient, dry=False):
	#Need to read in mappings and sync those notes.
	dryremotes = []
	try:
		with open('.snose', 'r') as f:
			snose = json.load(f)
	except IOError as e:
		print 'Error reading Index file'
	else:
		#Need to iterate through list.

		for name, local in snose.iteritems():
			#First of all check for local modifications
			sysmodifydate = float(os.path.getmtime(name))
			if sysmodifydate > float(local['modifydate']): #ensure full timestamp
				if not dry:
				#Update remote
					try:
						with open(name, 'r') as f:
							content = f.read()
					except IOError as e:
						print "Failed to read local note %s" % name
						print "Skipping synchronisation for this note"
					else: 
						try:
							returned = snclient.update_note({'key': local['key'], 'version': local['version'], 'content': content, 'modifydate': sysmodifydate })
							print "Updated remote version of %s" % name
						except IOError as e:
							print "Failed to update remote verison of local note %s" % name
						else:
							#Get returned metadata
							snose[name]['syncnum'] = returned[0]['syncnum']
							snose[name]['version'] = returned[0]['version']
							snose[name]['modifydate'] = sysmodifydate #Use local value to avoid differences in accuracy (decimal places. etc) between local and remote timestamps





















							#Update local file if merged content





							if 'content' in returned[0]:

								try:
									with open(name, 'w') as f:
										f.write(returned[0]['content'])
									print "Merged local content for %s" % name
									#Override the returned value? As otherwise next sync will immediately update the remote version for no reason.
									snose[name]['modifydate'] = os.path.getmtime(name) 
								except IOError as e:



									print "Failed to merge content locally for %s" % name
									print "Therefore skipping updating the index for this note" #I think this is a good idea?
							#Update the index file
							try:
								with open('.snose', 'w') as f:
									json.dump(snose, f, indent=2)
							except IOError as e:
								print "Failed to update index for changes regarding local file %s" % name


								print "But remote and local copy of the file itself have been updated."
								#What now? I don't know.


				elif dry:
					print "Updated remote version of %s" % name
					#For dry run, collect list of "updated remotes" to ignore in local updates
					dryremotes.append(name)
			#Fetch details from Simplenote
			try:
				remote = snclient.get_note(local['key'])
			except IOError as e:
				print "Failed to fetch remote copy of note %s" % name
				print "Skipping synchronisation for this file"


			else:


				if remote[0]['syncnum'] > local['syncnum']:
					if not dry:

						try: 

							with open(name, 'w') as f:



								f.write(remote[0]['content'])
							print "Updated local version of %s" % name
						except IOError as e:


							print "Failed to update local note %s with remote content" % name
							print "Will not updatet the .snose index file for this file"
						else:
							#Also update .snose index
							snose[name]['syncnum'] = remote[0]['syncnum']
							snose[name]['version'] = remote[0]['version']
							snose[name]['modifydate'] = os.path.getmtime(name) #As if set remote modify date, local file will immediately appear 'modified'
							try:
								with open('.snose', 'w') as f:
									json.dump(snose, f, indent=2)
							except IOError as e:
								print "Failed to update index"




								print "But local copy of the file %s has been updated with remote changes" % name
							#Some feedback


					elif (dry and (not (name in dryremotes))):



						print "Updated local version of %s" % name






main()