English
资源说明：A simple library for working with your CONTENTdm item and collection metadata as Python objects.
# Pycdm
Pycdm is a simple library for working with your CONTENTdm item and collection metadata as Python objects. Retrieve all metadata for an item and its pages with just a collection alias and item ID.
cookbook = pycdm.item('cookbooks', '2775')
Pycdm interfaces with the CONTENTdm 6 dmwebservices API to fetch metadata. You can also make direct calls to the API through the Api class:
#returns a decoded json response for a dmGetItemInfo call
call = Api()
iteminfo = call.dmGetItemInfo('cookbooks', '2775')
# Installation
Pycdm works with Python 2.7x only (solely to make use of the collections.OrderedDict subclass, which preserves Node and Page object sequence within dictionaries).
Install with pip:
$ pip install pycdm
(or easy_install):
$ easy_install pycdm
Open the pycdm.py file and replace the base and port variables with the base url and port of your CONTENTdm respository.
base = 'http://yourbaseurl.edu'
port = ':81'
# Examples
### Working with items and pages
#### Items
CONTENTdm items are one of three types: single page, compound object--document (a series of pages), or compound object--monograph (a series of pages organized into nodes, like a book divided into chapters). Calling the item() function creates an item object with attributes related to its descriptive and structural metadata. This includes:
* descriptive metadata record (item.info, Python dict where key=field nickname)
* the Dublin Core metadata record (item.dcinfo, Python dict where key= DC field nickname)
* CONTENTdm identifier (item.id)
* the Collection object the item is part of (item.collection)
* the reference URL for the item (item.refurl)
* the page structure of theitem object (item.structure)
* list of the item's constituent page objects (item.pages)
For single page items, you'll also get:
* URL for the stored file for the page (item.fileurl)
* URL for the default scaled/cropped JPEG image of a page image. Use the GetImage() method to set the URL with different parameters (item.imageurl)
* URL for the page thumbnail (item.thumburl)
To create an item object, use the item() call with collection alias and CONTENTdm item number:
>>>letter = pycdm.item('leighhunt', '1566')
This is a document type compound object:
>>>letter
Show the title of the item:
>>>letter.info['title']
u'Colburn Mayne letter to Leigh Hunt, September 30, 1850s'
Show the reference URL for the item:
>>> letter.refurl
'http://digital.lib.uiowa.edu/cdm/ref/collection/leighhunt/id/1566'
####Pages
Creating an item object in pycdm also creates page objects for each page of the item. This includes some basic metadata for each page:
* CONTENTdm identifier (.id)
* the page label (.label)
* the page's parent (item) identifier (.parentId)
* the pages parent node title (.parentnodetitle, defaults to parent item title if no parent node)
* the reference URL for the item (item.refurl)
* URL for the stored file for the page (item.fileurl)
* URL for the default scaled/cropped JPEG image of a page image. Use the GetImage() method to set the URL with different parameters (item.imageurl)
* URL for the page thumbnail (item.thumburl)
Including the "pageinfo='on'" attribute in the item() call will retrieve all of its pages' record and Dublin Core metadata as well. (The default is "pageinfo='off'" to reduce unneccessary calls to the API):
>>>letter = pycdm.item('leighhunt', '1566', pageinfo='on')
Show the page labels for each page of the letter:
>>> for p in letter.pages:
p.label
u'Page1'
u'Page2'
u'Page3'
u'Page4'
Print the page transcriptions for each page of the letter:
>>> for p in letter.pages:
print p.label + ': ' + p.info['transc']
Page1: September 30th
Dear Sir
Your kind letter followed me to the Co Wicklow, & reached, this morning, the Vicarage, where I am passing Michaelmas with my Brother in law a Church of England clergyman, attending church & was regularly as though I held all the Church of England doctrines; it was therefore the more refreshing to receive your few lines & learn from them that you were not displeased with my letter; In
Page2: the strangers land the language we are familiar with sounds the sweetest, & I own that orthodoxy, however moderate, (as it is here) seems to cramp & restrain my feelings; I long to breathe a freer air, or to get into a Corner with a "Book for a Corner" that may send my thoughts abroad in sympathy with human nature in all its varying phases. I grieve to learn that you have been unwell, yet, as long as the mind preserves its [ ? ], & the spirits their freshness, bodily weakness may be borne cheerfully, as it is, I am certain by you. I am glad you will read my novel; you will see how carelessly it has been
Page3: sent through the press, the truth is the publisher had no one to correct the proofs, & the thing was so new to me that my corrections but little improved them. this & other faults of the letter I trust you will not condemn, rather not condemn the books on their account, but look only to the Spirit in which there is I think something to please you. You will notice too that the feelings which prompted me to seek an interview with you at Hammersmith are of no recent date or hasty growth, & I trust the last chapter will not Cause you to dislike my hero & heroine for their taste in literature.
Page4: I must not trespass longer on
Your time and remain
Dear Sir
Yours very faithfully
Colburne Mayne
### Working with collections and metadata fields
#### Collections
Creating an item instance also creates a corresponding collection object. A collection object's attributes include:
* the collection alias (.alias)
* the collection name (.name)
* the URL for the digital collection (.url)
* the collection's metadata fields (.fields, a Python dict of field objects, where key=field nickname)
* the collection field mappings to Dublin Core (.dcmap, a Python dict, where key=field nickname)
Show an item's full collection name:
>>>leighhunt = letter.collection #first put the item's collection attribute into a variable
>>>leighhunt.name #then call the name attribute on the collection object
u'Leigh Hunt Letters'
>>>letter.collection.name #this works too
u'Leigh Hunt Letters'
You can also create a collection object directly:
>>>leighhunt = pycdm.Collection('leighhunt')
Calling the getItems() method on the collection will retrieve a list of all items identifiers in the collection and put it in the .item attribute:
>>>leighhunt.getItems()
>>>leighhunt.items
['51', '58', '63', '71', '76', '84', '89', '94', '99', '105', '110', '115', '125 ', '128', '141', '152', '156', '161', '166', '169', '173', '177', '183', '185', '194', '196', '199', '203', '206', '211', '214', '218', '223', '228', '262', '267', '272', '274', '277', '279', '283', '288', '294', '298', '303', '308', '311', '316', '321', '325', '330', '335', '339', '340', '344', '350', '355', '359', '362', '367', '370', '374', '379', '383', '388', '394', '399', '404', '409', '413'...]
Now you can iterate through every item in your collection (beware, this is A LOT of API calls):
>>>for i in leighhunt.items:
item = pycdm.item('leighhunt', i)
But maybe you just wanted to generate a list of all reference urls in the collection:
>>>for i in leighhunt.items:
print "http://digital.lib.uiowa.edu/cdm/ref/collection/leighhunt/id/" + i
####Fields
When a collection object is created, field objects are created for each of its metadata fields. Fields have full names and nicknames. When working with the API, nicknames are required for requesting field information in calls, but these nicknames can be hard to find within the admin interface. You can list all of the nicknames of field objects in a collection with Collection.fields, but that's not very readable:
>>> leighhunt.fields
{u'fullrs': , u'relati': , u'contac': , u'cited': , u'number': , u'dmrecord': , u'transd': , u'archiv': , u'oclc': , u'file': , u'topica': , u'topicb': , u'transa': , u'numbea': , u'transc': , u'creato': , u'subjec': , u'rights': , u'dmoclcno': , u'title': , u'publis': , u'find': , u'note': , u'source': , u'transb': , u'typa': , u'contri': , u'typb': , u'type': , u'descri': , u'promo': , u'object': , u'locati': , u'colleb': , u'collea': , u'date': , u'data': , u'dmmodified': , u'dmcreated': , u'catalo': , u'chrono': , u'corpor': , u'digitx': , u'upload': , u'place': , u'digiti': , u'width': }
Listing just the nicknames by using .keys() makes this a little more readable:
>>>leighhunt.fields.keys()
[u'fullrs', u'relati', u'contac', u'cited', u'number', u'dmrecord', u'transd', u'archiv', u'oclc', u'file', u'topica', u'topicb', u'transa', u'numbea', u'transc', u'creato', u'subjec', u'rights', u'dmoclcno', u'title', u'publis', u'find', u'note', u'source', u'transb', u'typa', u'contri', u'typb', u'type', u'descri', u'promo', u'object', u'locati', u'colleb', u'collea', u'date', u'data', u'dmmodified', u'dmcreated', u'catalo', u'chrono', u'corpor', u'digitx', u'upload', u'place', u'digiti', u'width']
But this still doesn't show us the corresponding full names of each field.
By looking into the field objects, we can learn more about a collection's fields. Attributes of fields include:
* the alias of the collection (.alias)
* the CDM nickname of the field (.nick)
* the Dublin Core mapping of the field (.dc)
* obligation of the field, where required=1 (.req)
* if the field is hidden, hidden=1 (.hide)
* if the field is indexed, search=1 (.search)
* if the field has controlled vocabulary, vocab=1 (.vocab)
* a list of the field's controlled vocabulary terms (.vocabterms)
Show the nickname and full name of each field (we'll sort them, too) for :
>>> for k, v in sorted(leighhunt.fields.items()):
print k + ": " + v.name
archiv: Archival Collection
catalo: Cataloged by
chrono: Chronological Subject
cited: Letter Published In
collea: Collection Guide
colleb: Collection Identifier
contac: Contact Information
contri: Contributing Institution
corpor: Corporate Name Subject
creato: Creator
data: Date Digital
date: Date Original
descri: Description
digiti: Digitization Specifications
digitx: Digital Collection
dmcreated: Date created
dmmodified: Date modified
dmoclcno: OCLC number
dmrecord: CONTENTdm number
...
We can also find the full name of a field from the collection object. List the full name of the 'date' field:
>>> leighhunt.fields['date'].name
u'Date Original'
Or the DC mapping. Get the Dublin Core mapping of the 'Topical Subject (LCSH)' ('topica') field:
>>> leighhunt.dcmap['topica']
u'subjec'
###CSV
Working with Unicode in Python is such a pain, isn't it? And much of the work you'll do with this library might involve dumping metadata into a CSV file in perfect UTF-8. The CSV object makes this a little easier by putting the work of creating a Unicode CSV writer in the library, so you dont have to.
Create a new CSV file to write to. Include a name for your file and a header row (optional):
>>>f = pycdm.CSV('myfile.csv', header=['foo', 'bar', 'one', 'two'])
Then do your stuff. To write a row of data to the csv file (where row = [your, list, of, values]:
>>>f.writerow(row)
Don't forget to close your file when you're finished:
>>>f.close()
###Catcher
Had I more time to work on this library I would have added more support for [Catcher](http://contentdm.org/help6/addons/catcher.asp), CONTENTdm's web service for batch metadata edits, but for now you can find a [catcher.py class](https://gist.github.com/saverkamp/9197945) and a [sample script](https://gist.github.com/saverkamp/9198310) over in GitHubGist.
###A word of caution!
If you haven't ever worked with the API or you don't manage your CONTENTdm server, please have a heart-to-heart with your sysadmin before you begin. Once you start working with many items or collections at once, it's very easy to generate many API calls, possibly enough to help crash your server. Your sysadmin can help you hack responsibly or give you the keys to a test instance.
# License
Copyright © 2012 Shawn Averkamp
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
