diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..3cd21bb --- /dev/null +++ b/Makefile @@ -0,0 +1,17 @@ +docs: magicmethods.html magicmethods.pdf clean + +html: magicmethods.html + +pdf: magicmethods.pdf + +magicmethods.html: markedup.html + cat header.html markedup.html footer.html > magicmethods.html + +markedup.html: table.markdown magicmethods.markdown table.markdown + python magicmarkdown.py + +magicmethods.pdf: magicmethods.tex + pdflatex magicmethods.tex + +clean: + rm -f markedup.html magicmethods.log magicmethods.dvi magicmethods.aux diff --git a/README.markdown b/README.markdown index 8cb7282..286d1e1 100644 --- a/README.markdown +++ b/README.markdown @@ -6,4 +6,4 @@ Licensed under Creative Commons CC--NC-BY-SA (see http://creativecommons.org/lic Can be seen at http://www.rafekettler.com/magicmethods.html in relatively up to date form. ## For forkers: ## -Edit magicmethods.mkd, run `python magicmarkdown.py`, and then `cat header.html markedup.html footer.html > magicmethods.html`. The magicmarkdown script requires markdown, just issue `pip install markdown` and you'll have it. \ No newline at end of file +Edit magicmethods.mkd/magicmethods.tex, then run `make docs`. The build script requires the Python Markdown module, so you'll have to run `pip install markdown` if you don't already have it. Happy hacking! \ No newline at end of file diff --git a/magicmarkdown.py b/magicmarkdown.py index 7c54d91..84a4796 100644 --- a/magicmarkdown.py +++ b/magicmarkdown.py @@ -1,38 +1,13 @@ -# magicmarkdown.py -# utility script for changing markdown from magic methods guide into HTML +""" + magicmarkdown.py +utility script for changing markdown from magic methods guide into HTML +""" import markdown -header = """ - - -A Guide to Python's Magic Methods « rafekettler.com - - - - - -""" - -footer = """ - - -""" - -table = open('table.mkd').read() -body = open('magicmethods.mkd').read() -appendix = open('appendix.mkd').read() +table = open('table.markdown').read() +body = open('magicmethods.markdown').read() +appendix = open('appendix.markdown').read() table_text = markdown.markdown(table) body_text = markdown.markdown(body, @@ -40,9 +15,7 @@ appendix_text = markdown.markdown(appendix, ['tables']) with open('magicmethods.html', 'w') as out: - out.write(header) out.write(table_text) out.write(body_text) out.write(appendix_text) - out.write(footer) diff --git a/magicmethods.html b/magicmethods.html index e681819..b4e9c6c 100644 --- a/magicmethods.html +++ b/magicmethods.html @@ -1,16 +1,7 @@ - - - -A Guide to Python's Magic Methods « rafekettler.com - - - - - -

A Guide to Python's Magic Methods

+

A Guide to Python's Magic Methods

Rafe Kettler

Copyright © 2011 Rafe Kettler

-

Version 1.12

+

Version 1.13

A PDF version of this guide can be obtained from my site or Github. The magic methods guide has a git repository at http://www.github.com/RafeKettler/magicmethods. Any issues can be reported there, along with comments, (or even contributions!).

Table of Contents

@@ -537,7 +528,7 @@

Building Descriptor Objects

Pickling Your Objects

-

If you spend time with other Pythonistas, chances are you've at least heard of pickling. Pickling is a serialization process for Python data structures, and can be incredibly useful when you need to store an object and retrieve it later. It's also a major source of worries and confusion.

+

If you spend time with other Pythonistas, chances are you've at least heard of pickling. Pickling is a serialization process for Python data structures, and can be incredibly useful when you need to store an object and retrieve it later (usually for caching). It's also a major source of worries and confusion.

Pickling is so important that it doesn't just have its own module (pickle), but its own protocol and the magic methods to go with it. But first, a brief word on how to pickle existing types(feel free to skip it if you already know).

Pickling: A Quick Soak in the Brine

Let's dive into pickling. Say you have a dictionary that you want to store and retrieve later. You couldwrite it's contents to a file, carefully making sure that you write correct syntax, then retrieve it using either exec() or processing the file input. But this is precarious at best: if you store important data in plain text, it could be corrupted or changed in any number of ways to make your program crash or worse run malicious code on your computer. Instead, we're going to pickle it:

@@ -563,6 +554,7 @@

Pickling: A Quick Soak in the Brine

What happens? Exactly what you expect. It's just like we had data all along.

+

Now, for a word of caution: pickling is not perfect. Pickle files are easily corrupted on accident and on purpose. Pickling may be more secure than using flat text files, but it still can be used to run malicious code. It's also incompatible across versions of Python, so don't expect to distribute pickled objects and expect people to be able to open them. However, it can also be a powerful tool for caching and other common serialization tasks.

Pickling your own Objects

Pickling isn't just for built-in types. It's for any class that follows the pickle protocol. The pickle protocol has four optional methods for Python objects to customize how they act (it's a bit different for C extensions, but that's not in our scope):

@@ -741,18 +733,4 @@

Conclusion

-

Hopefully, this table should have cleared up any questions you might have had about what syntax invokes which magic method.

- - - \ No newline at end of file +

Hopefully, this table should have cleared up any questions you might have had about what syntax invokes which magic method.

\ No newline at end of file diff --git a/magicmethods.pdf b/magicmethods.pdf index 5d9307c..50aafc6 100644 Binary files a/magicmethods.pdf and b/magicmethods.pdf differ diff --git a/table.markdown b/table.markdown index 384d081..2378f94 100644 --- a/table.markdown +++ b/table.markdown @@ -4,7 +4,7 @@ Copyright © 2011 Rafe Kettler -Version 1.12 +Version 1.13 A PDF version of this guide can be obtained from [my site](http://www.rafekettler.com/magicmethods.pdf) or [Github](https://github.com/RafeKettler/magicmethods/raw/master/magicmethods.pdf). The magic methods guide has [a git repository at http://www.github.com/RafeKettler/magicmethods](http://www.github.com/RafeKettler/magicmethods). Any issues can be reported there, along with comments, (or even contributions!).