mirror of
https://github.com/Mikaela/Limnoria.git
synced 2025-04-23 00:07:50 +02:00
Compare commits
No commits in common. "gh-pages" and "v0.80.0" have entirely different histories.
3
.cvsignore
Normal file
3
.cvsignore
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
*.pyc
|
||||||
|
*.pyo
|
||||||
|
*~
|
||||||
@ -1,8 +0,0 @@
|
|||||||
root = true
|
|
||||||
|
|
||||||
[*]
|
|
||||||
end_of_line = lf
|
|
||||||
trim_trailing_whitespace = false
|
|
||||||
insert_final_newline = true
|
|
||||||
charset = utf-8
|
|
||||||
indent_style = space
|
|
||||||
1
.gitattributes
vendored
1
.gitattributes
vendored
@ -1 +0,0 @@
|
|||||||
* text=auto eol=lf
|
|
||||||
1
.github/CODEOWNERS
vendored
1
.github/CODEOWNERS
vendored
@ -1 +0,0 @@
|
|||||||
* @Mikaela
|
|
||||||
5
.github/renovate.json5
vendored
5
.github/renovate.json5
vendored
@ -1,5 +0,0 @@
|
|||||||
/** @format */
|
|
||||||
|
|
||||||
{
|
|
||||||
extends: ["local>Mikaela/shell-things:.renovate-shared"],
|
|
||||||
}
|
|
||||||
25
.github/workflows/html5validator.yml.disabled
vendored
25
.github/workflows/html5validator.yml.disabled
vendored
@ -1,25 +0,0 @@
|
|||||||
name: HTML5 Validator
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4 # Required will all actions
|
|
||||||
|
|
||||||
- uses: ruby/setup-ruby@v1
|
|
||||||
with:
|
|
||||||
ruby-version: 3.1
|
|
||||||
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
|
|
||||||
|
|
||||||
- name: Jekyll build
|
|
||||||
run: |
|
|
||||||
bundle exec jekyll build --drafts --profile
|
|
||||||
|
|
||||||
- name: Checks HTML5 validity
|
|
||||||
uses: Cyb3r-Jak3/html5validator-action@v7.2.0
|
|
||||||
with:
|
|
||||||
root: _site/
|
|
||||||
blacklist: n r or ir
|
|
||||||
32
.gitignore
vendored
32
.gitignore
vendored
@ -1,32 +0,0 @@
|
|||||||
*.mo
|
|
||||||
*.py[cdo]
|
|
||||||
*~
|
|
||||||
.*.swp
|
|
||||||
.swp
|
|
||||||
MANIFEST
|
|
||||||
backup/
|
|
||||||
build/
|
|
||||||
debian/compat
|
|
||||||
debian/files
|
|
||||||
debian/limnoria*
|
|
||||||
debian/python-module-stampdir/
|
|
||||||
dist/
|
|
||||||
docs/_build/
|
|
||||||
docs/plugins/
|
|
||||||
limnoria.egg-info/
|
|
||||||
merge.sh
|
|
||||||
nano.save
|
|
||||||
push.sh
|
|
||||||
py3k/
|
|
||||||
src/version.py
|
|
||||||
supybot.egg-info/
|
|
||||||
test-conf/
|
|
||||||
test-data/
|
|
||||||
test-logs/
|
|
||||||
src/version.py
|
|
||||||
_site
|
|
||||||
.sass-cache
|
|
||||||
vendor/
|
|
||||||
.bundle
|
|
||||||
node_modules/
|
|
||||||
pnpm-lock.yaml
|
|
||||||
@ -1,83 +0,0 @@
|
|||||||
# @format
|
|
||||||
|
|
||||||
# SPDX-FileCopyrightText: 2023 Aminda Suomalainen <suomalainen+git@mikaela.info>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: CC0-1.0
|
|
||||||
|
|
||||||
# See https://pre-commit.com for more information
|
|
||||||
# See https://pre-commit.ci for more information
|
|
||||||
ci:
|
|
||||||
# I don't need so many duplicated notifications on the same thing as I keep
|
|
||||||
# autoupdating manually too. Besides it just creates extra branch I never
|
|
||||||
# touch.
|
|
||||||
# https://github.com/pre-commit-ci/issues/issues/83
|
|
||||||
autoupdate_schedule: quarterly
|
|
||||||
skip: [pnpm-install-dev, prettier]
|
|
||||||
|
|
||||||
repos:
|
|
||||||
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
||||||
rev: v5.0.0
|
|
||||||
hooks:
|
|
||||||
- id: trailing-whitespace
|
|
||||||
args: ["--markdown-linebreak-ext", "md,markdown"]
|
|
||||||
exclude_types: [svg, tsv]
|
|
||||||
- id: end-of-file-fixer
|
|
||||||
- id: check-yaml
|
|
||||||
- id: check-added-large-files
|
|
||||||
- id: check-case-conflict
|
|
||||||
- id: check-executables-have-shebangs
|
|
||||||
- id: check-json
|
|
||||||
- id: check-merge-conflict
|
|
||||||
- id: check-shebang-scripts-are-executable
|
|
||||||
- id: destroyed-symlinks
|
|
||||||
- id: detect-private-key
|
|
||||||
- id: fix-byte-order-marker
|
|
||||||
- id: check-merge-conflict
|
|
||||||
- id: mixed-line-ending
|
|
||||||
args: [--fix=auto]
|
|
||||||
- id: pretty-format-json
|
|
||||||
args: [--autofix, --no-ensure-ascii]
|
|
||||||
|
|
||||||
- repo: https://github.com/pre-commit-ci/pre-commit-ci-config
|
|
||||||
rev: v1.6.1
|
|
||||||
hooks:
|
|
||||||
- id: check-pre-commit-ci-config
|
|
||||||
|
|
||||||
- repo: https://github.com/thlorenz/doctoc
|
|
||||||
rev: v2.2.0
|
|
||||||
hooks:
|
|
||||||
- id: doctoc
|
|
||||||
args: [--update-only, --notitle]
|
|
||||||
|
|
||||||
- repo: https://github.com/python-jsonschema/check-jsonschema
|
|
||||||
rev: 0.33.0
|
|
||||||
hooks:
|
|
||||||
- id: check-dependabot
|
|
||||||
- id: check-github-workflows
|
|
||||||
- id: check-gitlab-ci
|
|
||||||
|
|
||||||
# - repo: https://github.com/fsfe/reuse-tool
|
|
||||||
# rev: v3.0.2
|
|
||||||
# hooks:
|
|
||||||
# - id: reuse
|
|
||||||
|
|
||||||
- repo: local
|
|
||||||
hooks:
|
|
||||||
- id: pnpm-install-dev
|
|
||||||
name: Install pnpm dev dependencies
|
|
||||||
entry: corepack pnpm install -D
|
|
||||||
language: system
|
|
||||||
always_run: true
|
|
||||||
#verbose: true
|
|
||||||
pass_filenames: false
|
|
||||||
- id: prettier
|
|
||||||
name: prettier
|
|
||||||
entry: corepack pnpm exec prettier --cache --ignore-unknown --write
|
|
||||||
language: system
|
|
||||||
|
|
||||||
- repo: https://github.com/editorconfig-checker/editorconfig-checker.python
|
|
||||||
rev: "3.2.1"
|
|
||||||
hooks:
|
|
||||||
- id: editorconfig-checker
|
|
||||||
alias: ec
|
|
||||||
args: [-disable-max-line-length]
|
|
||||||
@ -1,5 +0,0 @@
|
|||||||
_includes/
|
|
||||||
_layouts/
|
|
||||||
_sass/
|
|
||||||
css/
|
|
||||||
feed.xml
|
|
||||||
@ -1 +0,0 @@
|
|||||||
{}
|
|
||||||
@ -1 +0,0 @@
|
|||||||
3.4.2
|
|
||||||
@ -1,4 +0,0 @@
|
|||||||
# @format
|
|
||||||
|
|
||||||
language: ruby
|
|
||||||
script: "bundle exec jekyll build"
|
|
||||||
7
ACKS
Normal file
7
ACKS
Normal file
@ -0,0 +1,7 @@
|
|||||||
|
johhnyace, who gave me the modem that helped me tremendously in development.
|
||||||
|
bwp, who rewrote the Http.weather command, and also hosted the example
|
||||||
|
"supybot" in #supybot on OFTC and Freenode for quite some time.
|
||||||
|
sweede, for hosting the "main" supybot for awhile.
|
||||||
|
HostPC.com, for hosting the current example "supybot" and for graciously
|
||||||
|
providing DNS services and email.
|
||||||
|
|
||||||
10
BUGS
Normal file
10
BUGS
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
We're sure there are tons of them. When you find them, send them to us and
|
||||||
|
we'll fix them ASAP. We'd love to have a bugless bot someday...
|
||||||
|
|
||||||
|
Incidentally, the way to "send the bugs to us" is via SourceForge:
|
||||||
|
<http://sourceforge.net/tracker/?atid=489447&group_id=58965&func=browse>
|
||||||
|
|
||||||
|
Known bugs that probably won't get fixed:
|
||||||
|
|
||||||
|
BadWords' outFilter filters colors. It's not a high priority to get
|
||||||
|
that fixed.
|
||||||
67
DEVS
Normal file
67
DEVS
Normal file
@ -0,0 +1,67 @@
|
|||||||
|
These are the developers of Supybot, in approximate order of ____.
|
||||||
|
|
||||||
|
Jeremy Fincher (jemfinch) is a Computer Science (and possibly
|
||||||
|
philosophy) student at The Ohio State University. He spends most of
|
||||||
|
his free time with his girlfriend Meg, but also...well, there's not
|
||||||
|
much also :) He hopes to graduate with good enough grades to go to
|
||||||
|
law school or seminary at some point in the future. He initially
|
||||||
|
wrote the majority of the Supybot framework and standard plugins,
|
||||||
|
though he's been trying to slowly phase himself out of plugin-writing
|
||||||
|
and more into framework-enhancement. Rather than list the specific
|
||||||
|
things he's done, you can just assume that if someone else isn't
|
||||||
|
claiming it, it was probably done by him.
|
||||||
|
|
||||||
|
Daniel DiPaolo (Strike/ddipaolo) is a lazy Texan punk with a job as an IT
|
||||||
|
monkey who spends his free time coding, playing ultimate frisbee, and arguing
|
||||||
|
pointless things on the internet. As far as the bot goes, he's mainly a
|
||||||
|
plugin developer but he has helped here and there with various under-the-hood
|
||||||
|
things and is one of the few people (other than jemfinch) who understands the
|
||||||
|
inner workings of Supybot. His biggest plugin contribution (in terms of sheer
|
||||||
|
lines of code) has been the MoobotFactoids plugin and all the workd involved
|
||||||
|
in getting that plugin to work, but he has also helped with a lot of testing,
|
||||||
|
debugging, and brainstorming. He also wrote the Dunno, News, and Todo plugins
|
||||||
|
and is responsible for a significant amount of code in the Poll, Debian,
|
||||||
|
QuoteGrabs, Karma, and ChannelDB plugins.
|
||||||
|
|
||||||
|
James Vega (jamessan) is an Electrical Engineering/Computer Science student at
|
||||||
|
Northeastern University. He wrote the Sourceforge and Ebay plugins as well as
|
||||||
|
the first incarnation of the Babelfish commands and most of Amazon. He has
|
||||||
|
also performed a significant amount of maintenance and refactoring of plugins
|
||||||
|
in general. Some of the plugins that were affected the most are Debian,
|
||||||
|
FunDB, Gameknot, Http, Note, and Quote. All of the link snarfers, save
|
||||||
|
Bugzilla's, were also written by jamessan. His meddlings have prompted the
|
||||||
|
implementation of Toggleables, which eventually evolved to Configurables and
|
||||||
|
then to the current registry system. As well as being the current webmaster,
|
||||||
|
he also overhauled the tool which is used to generate the site's HTML
|
||||||
|
documentation for Supybot and setup the weekly creation of CVS snapshots.
|
||||||
|
|
||||||
|
Brett Kelly (inkedmn) is a hobbyist (soon to be professional :)) coder
|
||||||
|
from southern California who enjoys collecting tattoos (on his body) and
|
||||||
|
drinking coffee with his wife. He initially wrote the Note plugin as well
|
||||||
|
as several commands in the Http plugin.
|
||||||
|
|
||||||
|
Vincent Foley-Bourgon is a recently-graduated student from Quebec who
|
||||||
|
enjoys anything pointless, unprofitable, and generally useless. Recently
|
||||||
|
returning to Supybot development (after writing the original freshmeat
|
||||||
|
command for the Http plugin) he wrote the entire Hangman infrastructure
|
||||||
|
for the Words plugin.
|
||||||
|
|
||||||
|
Daniel Berlin is a soon to be lawyer with a background in computer science
|
||||||
|
and compilers. He enjoys selling crack to young homeless orphans, and works
|
||||||
|
on Supybot when he's not lawyering or hacking on gcc.
|
||||||
|
|
||||||
|
Keith Jones (kmj) dislikes talking about himself in the third person. He
|
||||||
|
has an MS in Computer Science, and has decided to see how long he can go
|
||||||
|
without using that in any kind of professional capacity. To that end he
|
||||||
|
is currently taking some math classes and applying to math Ph.D programs
|
||||||
|
so some day he can be a professor at a college near a snowy mountain where
|
||||||
|
he will ski every morning. So far, he hasn't done much for the project
|
||||||
|
except squeeze Doug Bell's GPL'd unit conversion code into a supybot plugin.
|
||||||
|
|
||||||
|
Stéphan Kochen (G-LiTe) is a lazy (soon to be) computer science student.
|
||||||
|
He's usually just freelancing and submitting patches here and there when he
|
||||||
|
bumps into a bug that bothers him, but Supybot is one of the first projects
|
||||||
|
he semi-actively tries to work on. ;) His biggest contribution has been the
|
||||||
|
refactoring of the supybot-wizard script to use the registry, though he also
|
||||||
|
likes to track down those nasty obscure bugs which haunt many of our fine
|
||||||
|
applications these days.
|
||||||
8
Gemfile
8
Gemfile
@ -1,8 +0,0 @@
|
|||||||
source "https://rubygems.org"
|
|
||||||
ruby file: ".ruby-version"
|
|
||||||
# For now this is a GitHub Pages hosted website.
|
|
||||||
# Ref: https://github.com/Mikaela/mikaela.github.io/issues/153
|
|
||||||
gem 'github-pages', group: :jekyll_plugins
|
|
||||||
gem 'jekyll-seo-tag'
|
|
||||||
# Required for `bundle exec jekyll serve`
|
|
||||||
gem "webrick"
|
|
||||||
286
Gemfile.lock
286
Gemfile.lock
@ -1,286 +0,0 @@
|
|||||||
GEM
|
|
||||||
remote: https://rubygems.org/
|
|
||||||
specs:
|
|
||||||
activesupport (8.0.2)
|
|
||||||
base64
|
|
||||||
benchmark (>= 0.3)
|
|
||||||
bigdecimal
|
|
||||||
concurrent-ruby (~> 1.0, >= 1.3.1)
|
|
||||||
connection_pool (>= 2.2.5)
|
|
||||||
drb
|
|
||||||
i18n (>= 1.6, < 2)
|
|
||||||
logger (>= 1.4.2)
|
|
||||||
minitest (>= 5.1)
|
|
||||||
securerandom (>= 0.3)
|
|
||||||
tzinfo (~> 2.0, >= 2.0.5)
|
|
||||||
uri (>= 0.13.1)
|
|
||||||
addressable (2.8.7)
|
|
||||||
public_suffix (>= 2.0.2, < 7.0)
|
|
||||||
base64 (0.2.0)
|
|
||||||
benchmark (0.4.0)
|
|
||||||
bigdecimal (3.1.9)
|
|
||||||
coffee-script (2.4.1)
|
|
||||||
coffee-script-source
|
|
||||||
execjs
|
|
||||||
coffee-script-source (1.12.2)
|
|
||||||
colorator (1.1.0)
|
|
||||||
commonmarker (0.23.11)
|
|
||||||
concurrent-ruby (1.3.5)
|
|
||||||
connection_pool (2.5.0)
|
|
||||||
csv (3.3.3)
|
|
||||||
dnsruby (1.72.4)
|
|
||||||
base64 (~> 0.2.0)
|
|
||||||
logger (~> 1.6.5)
|
|
||||||
simpleidn (~> 0.2.1)
|
|
||||||
drb (2.2.1)
|
|
||||||
em-websocket (0.5.3)
|
|
||||||
eventmachine (>= 0.12.9)
|
|
||||||
http_parser.rb (~> 0)
|
|
||||||
ethon (0.16.0)
|
|
||||||
ffi (>= 1.15.0)
|
|
||||||
eventmachine (1.2.7)
|
|
||||||
execjs (2.10.0)
|
|
||||||
faraday (2.13.0)
|
|
||||||
faraday-net_http (>= 2.0, < 3.5)
|
|
||||||
json
|
|
||||||
logger
|
|
||||||
faraday-net_http (3.4.0)
|
|
||||||
net-http (>= 0.5.0)
|
|
||||||
ffi (1.17.1-x86_64-linux-gnu)
|
|
||||||
forwardable-extended (2.6.0)
|
|
||||||
gemoji (4.1.0)
|
|
||||||
github-pages (232)
|
|
||||||
github-pages-health-check (= 1.18.2)
|
|
||||||
jekyll (= 3.10.0)
|
|
||||||
jekyll-avatar (= 0.8.0)
|
|
||||||
jekyll-coffeescript (= 1.2.2)
|
|
||||||
jekyll-commonmark-ghpages (= 0.5.1)
|
|
||||||
jekyll-default-layout (= 0.1.5)
|
|
||||||
jekyll-feed (= 0.17.0)
|
|
||||||
jekyll-gist (= 1.5.0)
|
|
||||||
jekyll-github-metadata (= 2.16.1)
|
|
||||||
jekyll-include-cache (= 0.2.1)
|
|
||||||
jekyll-mentions (= 1.6.0)
|
|
||||||
jekyll-optional-front-matter (= 0.3.2)
|
|
||||||
jekyll-paginate (= 1.1.0)
|
|
||||||
jekyll-readme-index (= 0.3.0)
|
|
||||||
jekyll-redirect-from (= 0.16.0)
|
|
||||||
jekyll-relative-links (= 0.6.1)
|
|
||||||
jekyll-remote-theme (= 0.4.3)
|
|
||||||
jekyll-sass-converter (= 1.5.2)
|
|
||||||
jekyll-seo-tag (= 2.8.0)
|
|
||||||
jekyll-sitemap (= 1.4.0)
|
|
||||||
jekyll-swiss (= 1.0.0)
|
|
||||||
jekyll-theme-architect (= 0.2.0)
|
|
||||||
jekyll-theme-cayman (= 0.2.0)
|
|
||||||
jekyll-theme-dinky (= 0.2.0)
|
|
||||||
jekyll-theme-hacker (= 0.2.0)
|
|
||||||
jekyll-theme-leap-day (= 0.2.0)
|
|
||||||
jekyll-theme-merlot (= 0.2.0)
|
|
||||||
jekyll-theme-midnight (= 0.2.0)
|
|
||||||
jekyll-theme-minimal (= 0.2.0)
|
|
||||||
jekyll-theme-modernist (= 0.2.0)
|
|
||||||
jekyll-theme-primer (= 0.6.0)
|
|
||||||
jekyll-theme-slate (= 0.2.0)
|
|
||||||
jekyll-theme-tactile (= 0.2.0)
|
|
||||||
jekyll-theme-time-machine (= 0.2.0)
|
|
||||||
jekyll-titles-from-headings (= 0.5.3)
|
|
||||||
jemoji (= 0.13.0)
|
|
||||||
kramdown (= 2.4.0)
|
|
||||||
kramdown-parser-gfm (= 1.1.0)
|
|
||||||
liquid (= 4.0.4)
|
|
||||||
mercenary (~> 0.3)
|
|
||||||
minima (= 2.5.1)
|
|
||||||
nokogiri (>= 1.16.2, < 2.0)
|
|
||||||
rouge (= 3.30.0)
|
|
||||||
terminal-table (~> 1.4)
|
|
||||||
webrick (~> 1.8)
|
|
||||||
github-pages-health-check (1.18.2)
|
|
||||||
addressable (~> 2.3)
|
|
||||||
dnsruby (~> 1.60)
|
|
||||||
octokit (>= 4, < 8)
|
|
||||||
public_suffix (>= 3.0, < 6.0)
|
|
||||||
typhoeus (~> 1.3)
|
|
||||||
html-pipeline (2.14.3)
|
|
||||||
activesupport (>= 2)
|
|
||||||
nokogiri (>= 1.4)
|
|
||||||
http_parser.rb (0.8.0)
|
|
||||||
i18n (1.14.7)
|
|
||||||
concurrent-ruby (~> 1.0)
|
|
||||||
jekyll (3.10.0)
|
|
||||||
addressable (~> 2.4)
|
|
||||||
colorator (~> 1.0)
|
|
||||||
csv (~> 3.0)
|
|
||||||
em-websocket (~> 0.5)
|
|
||||||
i18n (>= 0.7, < 2)
|
|
||||||
jekyll-sass-converter (~> 1.0)
|
|
||||||
jekyll-watch (~> 2.0)
|
|
||||||
kramdown (>= 1.17, < 3)
|
|
||||||
liquid (~> 4.0)
|
|
||||||
mercenary (~> 0.3.3)
|
|
||||||
pathutil (~> 0.9)
|
|
||||||
rouge (>= 1.7, < 4)
|
|
||||||
safe_yaml (~> 1.0)
|
|
||||||
webrick (>= 1.0)
|
|
||||||
jekyll-avatar (0.8.0)
|
|
||||||
jekyll (>= 3.0, < 5.0)
|
|
||||||
jekyll-coffeescript (1.2.2)
|
|
||||||
coffee-script (~> 2.2)
|
|
||||||
coffee-script-source (~> 1.12)
|
|
||||||
jekyll-commonmark (1.4.0)
|
|
||||||
commonmarker (~> 0.22)
|
|
||||||
jekyll-commonmark-ghpages (0.5.1)
|
|
||||||
commonmarker (>= 0.23.7, < 1.1.0)
|
|
||||||
jekyll (>= 3.9, < 4.0)
|
|
||||||
jekyll-commonmark (~> 1.4.0)
|
|
||||||
rouge (>= 2.0, < 5.0)
|
|
||||||
jekyll-default-layout (0.1.5)
|
|
||||||
jekyll (>= 3.0, < 5.0)
|
|
||||||
jekyll-feed (0.17.0)
|
|
||||||
jekyll (>= 3.7, < 5.0)
|
|
||||||
jekyll-gist (1.5.0)
|
|
||||||
octokit (~> 4.2)
|
|
||||||
jekyll-github-metadata (2.16.1)
|
|
||||||
jekyll (>= 3.4, < 5.0)
|
|
||||||
octokit (>= 4, < 7, != 4.4.0)
|
|
||||||
jekyll-include-cache (0.2.1)
|
|
||||||
jekyll (>= 3.7, < 5.0)
|
|
||||||
jekyll-mentions (1.6.0)
|
|
||||||
html-pipeline (~> 2.3)
|
|
||||||
jekyll (>= 3.7, < 5.0)
|
|
||||||
jekyll-optional-front-matter (0.3.2)
|
|
||||||
jekyll (>= 3.0, < 5.0)
|
|
||||||
jekyll-paginate (1.1.0)
|
|
||||||
jekyll-readme-index (0.3.0)
|
|
||||||
jekyll (>= 3.0, < 5.0)
|
|
||||||
jekyll-redirect-from (0.16.0)
|
|
||||||
jekyll (>= 3.3, < 5.0)
|
|
||||||
jekyll-relative-links (0.6.1)
|
|
||||||
jekyll (>= 3.3, < 5.0)
|
|
||||||
jekyll-remote-theme (0.4.3)
|
|
||||||
addressable (~> 2.0)
|
|
||||||
jekyll (>= 3.5, < 5.0)
|
|
||||||
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
|
|
||||||
rubyzip (>= 1.3.0, < 3.0)
|
|
||||||
jekyll-sass-converter (1.5.2)
|
|
||||||
sass (~> 3.4)
|
|
||||||
jekyll-seo-tag (2.8.0)
|
|
||||||
jekyll (>= 3.8, < 5.0)
|
|
||||||
jekyll-sitemap (1.4.0)
|
|
||||||
jekyll (>= 3.7, < 5.0)
|
|
||||||
jekyll-swiss (1.0.0)
|
|
||||||
jekyll-theme-architect (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-cayman (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-dinky (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-hacker (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-leap-day (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-merlot (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-midnight (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-minimal (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-modernist (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-primer (0.6.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-github-metadata (~> 2.9)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-slate (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-tactile (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-theme-time-machine (0.2.0)
|
|
||||||
jekyll (> 3.5, < 5.0)
|
|
||||||
jekyll-seo-tag (~> 2.0)
|
|
||||||
jekyll-titles-from-headings (0.5.3)
|
|
||||||
jekyll (>= 3.3, < 5.0)
|
|
||||||
jekyll-watch (2.2.1)
|
|
||||||
listen (~> 3.0)
|
|
||||||
jemoji (0.13.0)
|
|
||||||
gemoji (>= 3, < 5)
|
|
||||||
html-pipeline (~> 2.2)
|
|
||||||
jekyll (>= 3.0, < 5.0)
|
|
||||||
json (2.10.2)
|
|
||||||
kramdown (2.4.0)
|
|
||||||
rexml
|
|
||||||
kramdown-parser-gfm (1.1.0)
|
|
||||||
kramdown (~> 2.0)
|
|
||||||
liquid (4.0.4)
|
|
||||||
listen (3.9.0)
|
|
||||||
rb-fsevent (~> 0.10, >= 0.10.3)
|
|
||||||
rb-inotify (~> 0.9, >= 0.9.10)
|
|
||||||
logger (1.6.6)
|
|
||||||
mercenary (0.3.6)
|
|
||||||
minima (2.5.1)
|
|
||||||
jekyll (>= 3.5, < 5.0)
|
|
||||||
jekyll-feed (~> 0.9)
|
|
||||||
jekyll-seo-tag (~> 2.1)
|
|
||||||
minitest (5.25.5)
|
|
||||||
net-http (0.6.0)
|
|
||||||
uri
|
|
||||||
nokogiri (1.18.7-x86_64-linux-gnu)
|
|
||||||
racc (~> 1.4)
|
|
||||||
octokit (4.25.1)
|
|
||||||
faraday (>= 1, < 3)
|
|
||||||
sawyer (~> 0.9)
|
|
||||||
pathutil (0.16.2)
|
|
||||||
forwardable-extended (~> 2.6)
|
|
||||||
public_suffix (5.1.1)
|
|
||||||
racc (1.8.1)
|
|
||||||
rb-fsevent (0.11.2)
|
|
||||||
rb-inotify (0.11.1)
|
|
||||||
ffi (~> 1.0)
|
|
||||||
rexml (3.4.1)
|
|
||||||
rouge (3.30.0)
|
|
||||||
rubyzip (2.4.1)
|
|
||||||
safe_yaml (1.0.5)
|
|
||||||
sass (3.7.4)
|
|
||||||
sass-listen (~> 4.0.0)
|
|
||||||
sass-listen (4.0.0)
|
|
||||||
rb-fsevent (~> 0.9, >= 0.9.4)
|
|
||||||
rb-inotify (~> 0.9, >= 0.9.7)
|
|
||||||
sawyer (0.9.2)
|
|
||||||
addressable (>= 2.3.5)
|
|
||||||
faraday (>= 0.17.3, < 3)
|
|
||||||
securerandom (0.4.1)
|
|
||||||
simpleidn (0.2.3)
|
|
||||||
terminal-table (1.8.0)
|
|
||||||
unicode-display_width (~> 1.1, >= 1.1.1)
|
|
||||||
typhoeus (1.4.1)
|
|
||||||
ethon (>= 0.9.0)
|
|
||||||
tzinfo (2.0.6)
|
|
||||||
concurrent-ruby (~> 1.0)
|
|
||||||
unicode-display_width (1.8.0)
|
|
||||||
uri (1.0.3)
|
|
||||||
webrick (1.9.1)
|
|
||||||
|
|
||||||
PLATFORMS
|
|
||||||
x86_64-linux
|
|
||||||
|
|
||||||
DEPENDENCIES
|
|
||||||
github-pages
|
|
||||||
jekyll-seo-tag
|
|
||||||
webrick
|
|
||||||
|
|
||||||
RUBY VERSION
|
|
||||||
ruby 3.4.2p28
|
|
||||||
|
|
||||||
BUNDLED WITH
|
|
||||||
2.6.2
|
|
||||||
110
INSTALL
Normal file
110
INSTALL
Normal file
@ -0,0 +1,110 @@
|
|||||||
|
So what do you do? That depends on which operating system you're
|
||||||
|
running. We've split this document up to address the different
|
||||||
|
methods, so find the section for your operating system and continue
|
||||||
|
from there. First let's start with the parts that are common to all
|
||||||
|
OSes.
|
||||||
|
|
||||||
|
|
||||||
|
###
|
||||||
|
# COMMON:
|
||||||
|
###
|
||||||
|
|
||||||
|
First things first: Supybot *requires* at least Python 2.3. There ain't
|
||||||
|
no getting around it. We do not require any version greater than 2.3,
|
||||||
|
but we will be compatible with any version of Python >= 2.3. If you're
|
||||||
|
a Python developer, you probably know how superior 2.3 is to previous
|
||||||
|
incarnations. If you're not, just think about the difference between a
|
||||||
|
bowl of plain vanilla ice cream and a banana split. Or something like
|
||||||
|
that. Either way, *We're* Python developers and we like banana splits.
|
||||||
|
So, be sure to install python2.3 or greater before continuing. You can
|
||||||
|
get it from http://www.python.org/
|
||||||
|
|
||||||
|
For more information and help on how to use Supybot, checkout
|
||||||
|
the documents under docs/ (especially GETTING_STARTED and CONFIGURATION).
|
||||||
|
Our forums (http://forums.supybot.org/) may also be of use, especially
|
||||||
|
the "Tips and Tricks" topic under "Supybot User Discussion".
|
||||||
|
|
||||||
|
|
||||||
|
###
|
||||||
|
# UNIX/Linux/*BSD:
|
||||||
|
###
|
||||||
|
|
||||||
|
If you're installing Python using your distributor's packages, you may
|
||||||
|
need a python-dev package installed, too. If you don't have a
|
||||||
|
/usr/lib/python2.3/distutils directory (assuming /usr/lib/python2.3 is
|
||||||
|
where your Python libs are installed), then you will need a python-dev
|
||||||
|
package.
|
||||||
|
|
||||||
|
After you extract Supybot and cd into the supybot directory just
|
||||||
|
created, you'll want to run (as root) "python setup.py install". This
|
||||||
|
will install Supybot globally. If you need to install locally for
|
||||||
|
whatever reason, see the addendum near the end of this document.
|
||||||
|
You'll then have several new programs installed where Python scripts
|
||||||
|
are normally installed on your system (/usr/bin or /usr/local/bin are
|
||||||
|
common on UNIX systems). The two that might be of particular interest
|
||||||
|
to you, the new user, are "supybot" and "supybot-wizard". The former
|
||||||
|
("supybot") is the script to run an actual bot; the latter
|
||||||
|
("supybot-wizard") is an in-depth wizard that provides a nice user
|
||||||
|
interface for creating a registry file for your bot.
|
||||||
|
|
||||||
|
So after running supybot-wizard, you've got a nice registry file
|
||||||
|
handy. If you're not satisfied with your answers to any of the
|
||||||
|
questions you were asked, feel free to run the program again until
|
||||||
|
you're satisfied with all your answers. Once you're satisfied,
|
||||||
|
though, run the "supybot" program with the registry file you created
|
||||||
|
as an argument. This will start the bot; unless you turned off
|
||||||
|
logging to stdout, you'll see some nice log messages describing what
|
||||||
|
the bot is doing at any particular moment; it may pause for a
|
||||||
|
significant amount of time after saying "Connecting to ..." while the
|
||||||
|
server tries to check its ident.
|
||||||
|
|
||||||
|
|
||||||
|
###
|
||||||
|
# Windows:
|
||||||
|
###
|
||||||
|
|
||||||
|
*** If you are using an IPV6 connection, you will not be able to run
|
||||||
|
Supybot under Windows (unless Python has fixed things). Current
|
||||||
|
versions of Python for Windows are *not* built with IPV6 support. This
|
||||||
|
isn't expected to be fixed until Python 2.4, at the earliest.
|
||||||
|
|
||||||
|
Now that you have Python installed, open up a command prompt. The
|
||||||
|
easiest way to do this is to open the run dialog (Programs -> run) and
|
||||||
|
type "cmd" (for Windows 2000/XP/2003) or "command" (for Windows 9x).
|
||||||
|
In order to reduce the amount of typing you need to do, I suggest
|
||||||
|
adding Python's directory to your path. If you installed Python using
|
||||||
|
the default settings, you would then do the following in the command
|
||||||
|
prompt (otherwise change the path to match your settings):
|
||||||
|
|
||||||
|
set PATH=%PATH%;C:\Python23\
|
||||||
|
|
||||||
|
You should now be able to type "python" to start the Python
|
||||||
|
interpreter (CTRL-Z and Return to exit). Now that that's setup,
|
||||||
|
you'll want to cd into the directory that was created when you
|
||||||
|
unzipped Supybot; I'll assume you unzipped it to C:\Supybot for these
|
||||||
|
instructions. From C:\Supybot, run "python setup.py install". This
|
||||||
|
will install Supybot under C:\Python23\. If you want to install
|
||||||
|
Supybot to a non-default location, see the addendum near the end of
|
||||||
|
this document. You will now have several new programs installed in
|
||||||
|
C:\Python23\Scripts\. The two that might be of particular interest to
|
||||||
|
you, the new user, are "supybot" and "supybot-wizard". The former
|
||||||
|
("supybot") is the script to run an actual bot; the latter
|
||||||
|
("supybot-wizard") is an in-depth wizard that provides a nice user
|
||||||
|
interface for creating a registry file for your bot.
|
||||||
|
|
||||||
|
Now you will want to run "python C:\Python23\Scripts\supybot-wizard"
|
||||||
|
to generate a registry file for your bot. So after running
|
||||||
|
supybot-wizard, you've got a nice registry file handy. If you're not
|
||||||
|
satisfied with your answers to any of the questions you were asked,
|
||||||
|
feel free to run the program again until you're satisfied with all
|
||||||
|
your answers. Once you're satisfied, though, run "python
|
||||||
|
C:\Python23\Scripts\supybot botname.conf". This will start the bot;
|
||||||
|
unless you turned off logging to stdout, you'll see some nice log
|
||||||
|
messages describing what the bot is doing at any particular moment; it
|
||||||
|
may pause for a significant amount of time after saying "Connecting
|
||||||
|
to ..." while the server tries to check its ident.
|
||||||
|
|
||||||
|
###
|
||||||
|
# Addenda
|
||||||
|
###
|
||||||
|
Local installs: See this forum post: http://tinyurl.com/2tb37
|
||||||
28
LICENSE
Normal file
28
LICENSE
Normal file
@ -0,0 +1,28 @@
|
|||||||
|
Copyright (c) 2002-2004 Jeremiah Fincher and others
|
||||||
|
All rights reserved.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without
|
||||||
|
modification, are permitted provided that the following conditions are met:
|
||||||
|
|
||||||
|
* Redistributions of source code must retain the above copyright notice,
|
||||||
|
this list of conditions, and the following disclaimer.
|
||||||
|
* Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
this list of conditions, and the following disclaimer in the
|
||||||
|
documentation and/or other materials provided with the distribution.
|
||||||
|
* Neither the name of the author of this software nor the name of
|
||||||
|
contributors to this software may be used to endorse or promote products
|
||||||
|
derived from this software without specific prior written permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||||
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||||
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||||
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
|
||||||
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||||
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||||
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||||
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||||
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
|
||||||
|
Portions of the included source code are copyright by its original author(s)
|
||||||
|
and remain subject to its associated license.
|
||||||
38
README
Normal file
38
README
Normal file
@ -0,0 +1,38 @@
|
|||||||
|
EVERYONE:
|
||||||
|
---------
|
||||||
|
Read LICENSE. It's a 2-clause BSD license, but you should read it anyway.
|
||||||
|
|
||||||
|
|
||||||
|
USERS:
|
||||||
|
------
|
||||||
|
If you're upgrading, read RELNOTES. If you're new to Supybot,
|
||||||
|
read docs/GETTING_STARTED for an introduction to the bot, and read
|
||||||
|
docs/CAPABILITIES to see how to use capabilities to your greater
|
||||||
|
benefit.
|
||||||
|
|
||||||
|
If you have any trouble, feel free to swing by #supybot on
|
||||||
|
irc.freenode.net or irc.oftc.net (we have a Supybot there relaying,
|
||||||
|
so either network works) and ask questions. We'll be happy to help
|
||||||
|
wherever we can. And by all means, if you find anything hard to
|
||||||
|
understand or think you know of a better way to do something,
|
||||||
|
*please* post it on Sourceforge.net so we can improve the bot!
|
||||||
|
|
||||||
|
WINDOWS USERS:
|
||||||
|
--------------
|
||||||
|
The wizards (supybot-wizard, supybot-newplugin, and
|
||||||
|
supybot-adduser) are all installed to your Python directory's
|
||||||
|
\Scripts. What that *probably* means is that you'll run them like
|
||||||
|
this: C:\Python23\python C:\Python23\Scripts\supybot-wizard
|
||||||
|
|
||||||
|
|
||||||
|
DEVELOPERS:
|
||||||
|
-----------
|
||||||
|
Read OVERVIEW to see what the modules are used for. Read PLUGIN-EXAMPLE
|
||||||
|
to see some examples of callbacks and commands written for the bot.
|
||||||
|
Read INTERFACES to see what kinds of objects you'll be dealing with.
|
||||||
|
Read STYLE if you wish to contribute; all contributed code must meet
|
||||||
|
the guidelines set forth there.
|
||||||
|
|
||||||
|
Be sure to run "test/test.py --help" to see what options are available
|
||||||
|
to you when testing. Windows users in particular should be sure to
|
||||||
|
exclude test_Debian.py and test_Unix.py.
|
||||||
11
README.md
11
README.md
@ -1,11 +0,0 @@
|
|||||||
<!-- @format -->
|
|
||||||
|
|
||||||
# Mikaela's fork of Limnoria.
|
|
||||||
|
|
||||||
There are mainly two branches. This one which you are looking at, gh-pages which
|
|
||||||
is the source of <https://supybot.mikaela.info/>.
|
|
||||||
|
|
||||||
**testing** which will be synced with [ProgVal/Limnoria] when needed. It is used
|
|
||||||
as base for my changes which will be pull requested.
|
|
||||||
|
|
||||||
[ProgVal/Limnoria]: https://github.com/ProgVal/Limnoria.git
|
|
||||||
257
RELNOTES
Normal file
257
RELNOTES
Normal file
@ -0,0 +1,257 @@
|
|||||||
|
Version 0.80.0
|
||||||
|
|
||||||
|
We *finally* hit 0.80.0! This release is completely compatible with
|
||||||
|
the last release candidate.
|
||||||
|
|
||||||
|
An update to Babelfish may cause an error message to be displayed in
|
||||||
|
the console when the bot is first run. The error message should be
|
||||||
|
gone when the bot is restarted.
|
||||||
|
|
||||||
|
We also have a new community website at http://www.supybot.com/ where
|
||||||
|
our users can submit their own plugins, view/download other people's
|
||||||
|
plugins and discuss all things Supybot-related.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0rc3
|
||||||
|
|
||||||
|
Another bugfix release. This one was pretty important as it actually
|
||||||
|
makes supybot.database.plugins.channelSpecific work properly.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0rc2
|
||||||
|
|
||||||
|
supybot.databases.plugins.channelSpecific.channel was renamed to
|
||||||
|
supybot.databases.plugins.channelSpecific.link.
|
||||||
|
|
||||||
|
supybot.databases.plugins.channelSpecific.link.allow was added, which
|
||||||
|
determines whether a channel will allow other channels to link to its
|
||||||
|
database.
|
||||||
|
|
||||||
|
Infobot is no longer deprecated and the following changes were made to
|
||||||
|
its config variables:
|
||||||
|
supybot.plugins.Infobot.answerUnaddressedQuestions was renamed to
|
||||||
|
supybot.plugins.Infobot.unaddressed.answerQuestions.
|
||||||
|
supybot.plugins.Infobot.snarfUnaddressedDefinitions was renamed to
|
||||||
|
supybot.plugins.Infobot.unaddressed.snarfDefinitions.
|
||||||
|
supybot.plugins.Infobot.unaddressed.replyExistingFactoid was added to
|
||||||
|
determine whether the bot will reply when someone attempts to create a
|
||||||
|
duplicate factoid.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre6
|
||||||
|
|
||||||
|
Another bugfix release. No incompatibilities known. The only
|
||||||
|
registry change is that supybot.databases.users.hash has been
|
||||||
|
removed.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre5
|
||||||
|
|
||||||
|
Completely bugfix release. No incompatibilies known.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre4
|
||||||
|
|
||||||
|
Mainly a bug fix release. This will likely be the last release before
|
||||||
|
0.80.0final, but we're gonna let it stew for a couple weeks to attempt
|
||||||
|
to catch any lingering bugs.
|
||||||
|
|
||||||
|
ansycoreDrivers is now deprecated in favor of socketDrivers or
|
||||||
|
twistedDrivers.
|
||||||
|
|
||||||
|
supybot.databases.plugins.channelSpecific.channel is now a channelValue
|
||||||
|
so that you can link specific channels together (instead of all channels
|
||||||
|
being linked together).
|
||||||
|
|
||||||
|
For those of you that use eval and/or exec, they have been removed from
|
||||||
|
the Owner plugin and are now in sandbox/Debug.py (which you'll have to
|
||||||
|
grab from CVS).
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre3
|
||||||
|
|
||||||
|
The database format for the Note plugin has changed to a flatfile
|
||||||
|
format; use tools/noteConvert.py to convert it to the new format.
|
||||||
|
|
||||||
|
Ditto that for the URL database.
|
||||||
|
|
||||||
|
FunDB is deprecated and will be removed at the next major release;
|
||||||
|
use tools/fundbConvert.py to convert your old FunDB databases to Lart
|
||||||
|
and Praise databases.
|
||||||
|
|
||||||
|
If you had turned off supybot.databases.plugins.channelSpecific, your
|
||||||
|
non-channel-specific database files had gone directly into your data/
|
||||||
|
directory. We had some problems with poor interactions between that
|
||||||
|
configuration variable and channel capabilities, though, so we
|
||||||
|
changed the implementation so that non-channel-specific databases are
|
||||||
|
considered databases of a single (configurable) channel (defaulting
|
||||||
|
to "#"). This will also help others who are converting from
|
||||||
|
channel-specific to non-channel-specific databases, but for you
|
||||||
|
who've already made the switch, you'll need to move your database
|
||||||
|
files again, from data/ to data/# (or whatever channel you might
|
||||||
|
change that variable to).
|
||||||
|
|
||||||
|
supybot.channels doesn't exist anymore; now the only list of channels
|
||||||
|
to join is per-network, in supybot.networks.<network>.channels.
|
||||||
|
|
||||||
|
We weren't serializing supybot.replies.* properly in older versions.
|
||||||
|
Now we are, but the old, improperly serialized versions won't work
|
||||||
|
properly. Remove from your configuration file all variables
|
||||||
|
beginning with "supybot.replies" before you start the bot.
|
||||||
|
|
||||||
|
The URL database has been changed again, but it will use a different
|
||||||
|
filename so you shouldn't run into conflicts, just a newly-empty
|
||||||
|
database.
|
||||||
|
|
||||||
|
We upgraded the SOAP stuff in others; you may do well to do a
|
||||||
|
setup.py install --clean this time around.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre2
|
||||||
|
|
||||||
|
Many more bugs have been fixed. A few more plugins have been updated
|
||||||
|
to use our new-style database abstraction. If it seems like your
|
||||||
|
databases are suddenly empty, look for a new database file named
|
||||||
|
Plugin.dbtype.db. We've also added a few more configuration variables.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.80.0pre1
|
||||||
|
|
||||||
|
Tons of bugs fixed, many features and plugins added. Everything
|
||||||
|
should be entirely compatible; many more configuration variables have
|
||||||
|
been added.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.79.9999
|
||||||
|
|
||||||
|
Some more bugs fixed, added a few features and a couple configuration
|
||||||
|
variabless. This should hopefully be the last release before 0.80.0,
|
||||||
|
which will finally bring us to pure Beta status.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.79.999
|
||||||
|
|
||||||
|
Some bugs fixed, but the ones that were fixed were pretty big. This
|
||||||
|
is, of course, completely compatible with the last release.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.79.99
|
||||||
|
|
||||||
|
Many bugs fixed, thanks to the users who reported them. We're
|
||||||
|
getting asymptotically closer to 0.80.0 -- maybe this'll be the last
|
||||||
|
one, maybe we'll have to release an 0.79.999 -- either way, we're
|
||||||
|
getting close :) Check out the ChangeLog for the fixes and a few new
|
||||||
|
features.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.79.9
|
||||||
|
|
||||||
|
We've changed so much stuff in this release that we've given up on
|
||||||
|
users upgrading their configuration files for the new release. So
|
||||||
|
do a clean install (python2.3 setup.py install --clean), run the
|
||||||
|
wizard again, and kick some butt.
|
||||||
|
|
||||||
|
(It's rumored that you can save most of your old configuration by
|
||||||
|
appending your new configuration at the end of your old configuration
|
||||||
|
and running supybot with that new configuration file. This, of
|
||||||
|
course, comes with no warranty or guarantee of utility -- try it if
|
||||||
|
you want, but backup your original configuration file!)
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.77.2
|
||||||
|
|
||||||
|
This is a drop-in replacement for 0.77.1, with two exceptions. The
|
||||||
|
configuration variable formerly known as
|
||||||
|
"supybot.plugins.Services.password" is now known as
|
||||||
|
"supybot.plugins.Services.NickServ.password", due to the fact that
|
||||||
|
there might be different passwords for NickServ and ChanServ (and
|
||||||
|
ChanServ passwords are per-channel, whereas NickServ passwords are
|
||||||
|
global). If you're using the Services plugin, you'll need to make
|
||||||
|
this change in order to continue identifying with services. The
|
||||||
|
configuration variable formerly known as
|
||||||
|
"supybot.plugins.Babelfish.disabledLanguages" is now known as
|
||||||
|
"supybot.plugins.Babelfish.languages". The configuration variable now
|
||||||
|
accepts the languages that *will* be translated as opposed to ones
|
||||||
|
that are *not* translated.
|
||||||
|
|
||||||
|
Tests and the developer sandbox are not longer delivered with our
|
||||||
|
release tarballs. If you're a developer and you want these, you
|
||||||
|
should either check out CVS or download one of our weekly CVS
|
||||||
|
snapshots, available at http://supybot.sourceforge.net/snapshots/ .
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.77.1
|
||||||
|
|
||||||
|
This is a drop-in replacement for 0.77.0 -- no incompatibilities, to
|
||||||
|
out knowledge. Simply install over your old installation and restart
|
||||||
|
your bot :)
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.77.0
|
||||||
|
|
||||||
|
Setup.py will automatically remove your old installations for you, no
|
||||||
|
need to worry about that yourself.
|
||||||
|
|
||||||
|
Configuration has been *entirely* redone. Read the new
|
||||||
|
GETTING_STARTED document to see how to work with configuration
|
||||||
|
variables now. Your old botscripts from earlier versions *will not*
|
||||||
|
work with the new configuration method. We'd appreciate it if you'd
|
||||||
|
rerun the wizard in order for us to find any bugs that remain in it
|
||||||
|
before we officially declare ourselves Beta. Note also that because
|
||||||
|
of the new configuration method, the interface for plugins' configure
|
||||||
|
function has changed: there are no longer any onStart or afterConnect
|
||||||
|
arguments, so all configuration should be performed via the registry.
|
||||||
|
|
||||||
|
Channel capabilities have been changed; rather than being
|
||||||
|
#channel.capability, they're now #channel,capability. It's a bit
|
||||||
|
uglier, we know, but dots can be valid in channel names, and we
|
||||||
|
needed the dot for handling plugin.command capabilities.
|
||||||
|
tools/ircdbConvert.py should update this for you.
|
||||||
|
|
||||||
|
The on-disk format of the user/channel databases has changed to be far
|
||||||
|
more readable. A conversion utility is included, as mentioned before:
|
||||||
|
tools/ircdbConvert.py. Run this with no arguments to see the
|
||||||
|
directions for using it.
|
||||||
|
|
||||||
|
Uh, we were just kidding about the upgrade script in 0.76.0 :) It'll
|
||||||
|
be a little while longer. We do have several little upgrade scripts,
|
||||||
|
though.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.76.1
|
||||||
|
|
||||||
|
Almost entirely bugfixes, just some minor (and some less minor) bugs
|
||||||
|
that need to get in before we really start hacking on the next
|
||||||
|
version. Should be *entirely* compatible with 0.76.0.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.76.0
|
||||||
|
|
||||||
|
Major bugfix release. A great number of bugs fixed. This is the last
|
||||||
|
release without an upgrade script.
|
||||||
|
|
||||||
|
The only hiccup in the upgrade from 0.75.0 should be that you'll need
|
||||||
|
to update your botscript to reflect the removal of the debug module.
|
||||||
|
We'd rather you use supybot-wizard to generate a new botscript, of
|
||||||
|
course, but if you insist on modifying your existing botscript, take a
|
||||||
|
look at
|
||||||
|
<http://cvs.sourceforge.net/viewcvs.py/supybot/supybot/src/template.py?r1=1.20&r2=1.21>
|
||||||
|
to see what you need to do.
|
||||||
|
|
||||||
|
|
||||||
|
Version 0.75.0
|
||||||
|
|
||||||
|
Don't forget to reinstall (i.e., run "python setup.py install" as
|
||||||
|
root). Sometimes it even does good to remove the old installation;
|
||||||
|
$PYTHON/site-packages/supybot can be removed with no problems
|
||||||
|
whatsoever.
|
||||||
|
|
||||||
|
You will need to re-run supybot-wizard and generate a new botscript.
|
||||||
|
|
||||||
|
The Infobot plugin has been removed from this release; it's not ready
|
||||||
|
for prime time. If you're interested in getting it running (i.e., you
|
||||||
|
want full Infobot compatibility and aren't satisfied with either
|
||||||
|
MoobotFactoids or Factoids) then swing over to #supybot and we can
|
||||||
|
discuss the tests. We simply don't know enough about Infobot to make
|
||||||
|
sure our Infobot plugin is an exact replica, and need someone's help
|
||||||
|
with making the changes necessary for that.
|
||||||
@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
layout: page
|
|
||||||
title: Ignoring RelayBot
|
|
||||||
permalink: /Relaybot.html
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- @format -->
|
|
||||||
|
|
||||||
RelayBot is the bot which relays between #supybot,#limnoria at a couple of
|
|
||||||
networks (TODO/FIXME, which ones?). It is currently using the
|
|
||||||
[LinkRelay](https://github.com/ProgVal/Supybot-plugins/tree/master/LinkRelay)
|
|
||||||
plugin to do this.
|
|
||||||
|
|
||||||
It's sometimes considered as annoyance as it has lately mostly spammed with join
|
|
||||||
(part messages aren't working, because of a bug (2014-06-23)) messages of people
|
|
||||||
who usually say nothing and this is why this page is here to tell how to ignore
|
|
||||||
it on various client.
|
|
||||||
|
|
||||||
We(who? I?) encourage you to ignore only notices from RelayBot instead of
|
|
||||||
everything as there are people whom should be heard at OFTC (mainly main Supybot
|
|
||||||
developer). (TODO/FIXME: is this the case in 2021?)
|
|
||||||
|
|
||||||
Related links:
|
|
||||||
|
|
||||||
- [LinkRelay plugin](https://github.com/ProgVal/Supybot-plugins/tree/master/LinkRelay)
|
|
||||||
- [Feature request for smart filtering of joins/quits/parts](https://github.com/ProgVal/Supybot-plugins/issues/66)
|
|
||||||
- [Feature request for RELAYMSG for more native look&feel](https://github.com/ProgVal/Supybot-plugins/issues/338)
|
|
||||||
|
|
||||||
Hostmask of RelayBot on Libera.Chat 2021-06-06:
|
|
||||||
|
|
||||||
- `RelayBot!~limnoria@helium.progval.net`
|
|
||||||
- This is absolute hostmask, also known as NUH (`nick!user@host`)
|
|
||||||
- `RelayBot*!*@helium.progval.net`
|
|
||||||
- This is recommended hostmask as it matches RelayBot even if it cannot use
|
|
||||||
it's primary nickname or networks cannot connect to it's identd.
|
|
||||||
|
|
||||||
## HexChat
|
|
||||||
|
|
||||||
From the "Window" menu you can find "Ignore list". Click "Add" and add one of
|
|
||||||
the hostmasks mentioned above (the lower is recommended).
|
|
||||||
|
|
||||||
Uncheck the other checkboxes than "Notice" and you can close the window and you
|
|
||||||
won't see spamming.
|
|
||||||
|
|
||||||
## KVIRC
|
|
||||||
|
|
||||||
I am not primarily KVIRC user and I cannot say anything else than right click
|
|
||||||
RelayBot and select something that matches only RelayBot.
|
|
||||||
|
|
||||||
**WARNING: KVIRC makes it very easy to also ignore pinkieval which you don't
|
|
||||||
want to do as they are author of Limnoria and help people often!**
|
|
||||||
|
|
||||||
## Linkinus
|
|
||||||
|
|
||||||
According to another person, there is a GUI where you can easily ignore notices
|
|
||||||
from specific hostmask.
|
|
||||||
|
|
||||||
## WeeChat
|
|
||||||
|
|
||||||
`/filter add relaybotnotices * irc_notice+nick_RelayBot *`
|
|
||||||
|
|
||||||
This creates a new filter with the name "relaybotnotices" which filters all
|
|
||||||
notices from the nickname "RelayBot".
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
This page is very likely missing many IRC clients. Could you
|
|
||||||
[open an issue](https://github.com/mikaela/limnoria/issues) about how to do this
|
|
||||||
with your IRC client that isn't mentioned here?
|
|
||||||
|
|
||||||
---
|
|
||||||
145
Supybot.markdown
145
Supybot.markdown
@ -1,145 +0,0 @@
|
|||||||
---
|
|
||||||
layout: page
|
|
||||||
title: Security issues
|
|
||||||
permalink: /Supybot.html
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- @format -->
|
|
||||||
|
|
||||||
Supybot git repository was declared dead on 2018-05-10 and archived on GitHub.
|
|
||||||
[v0.84.0 was the last release at that time](https://github.com/Supybot/Supybot/releases/tag/v0.84.0).
|
|
||||||
0.83.4.1 used to be a very common release available through several Linux
|
|
||||||
distributions for years and thus I made this page, which I guess is now
|
|
||||||
available more of for historical reasons.
|
|
||||||
|
|
||||||
**_WARNING: most of the content originates from 2014!_**
|
|
||||||
|
|
||||||
## The issues of 0.83.4.1.
|
|
||||||
|
|
||||||
### 1. Anyone can crash it and computer where it's running on
|
|
||||||
|
|
||||||
And this is very easy. Just run the command
|
|
||||||
|
|
||||||
`!misc last --regexp m/(.*\w){512}/`
|
|
||||||
|
|
||||||
where ! is the prefix character.
|
|
||||||
|
|
||||||
Misc is loaded by default and cannot be unloaded without modifying the config.
|
|
||||||
|
|
||||||
- [Limnoria issue #157](https://github.com/ProgVal/Limnoria/issues/157)
|
|
||||||
- Fixing commits:
|
|
||||||
[3526d5d](https://github.com/ProgVal/Limnoria/commit/3526d5dabf587457a43af8bee8d4db21986e8222)
|
|
||||||
&
|
|
||||||
[e11dc28](https://github.com/ProgVal/Limnoria/commit/e11dc28025de877b1b6cf059013eef88337b7e44)
|
|
||||||
- [Ubuntu bug #996947](https://bugs.launchpad.net/ubuntu/+source/supybot/+bug/996947)
|
|
||||||
- [Debian bug #672214](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=672214)
|
|
||||||
|
|
||||||
### 2. The previous wasn't the only way to do this
|
|
||||||
|
|
||||||
Everyone can also make the bot count an equation, which brings it and the host
|
|
||||||
computer down.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
`!math calc factorial(999999)`
|
|
||||||
|
|
||||||
This requires Math plugin which comes with Supybot, but isn't load by default.
|
|
||||||
|
|
||||||
- [Limnoria issue #354](https://github.com/ProgVal/Limnoria/issues/354)
|
|
||||||
- Fixing commit:
|
|
||||||
[695078e](https://github.com/ProgVal/Limnoria/commit/695078edeb91e5ff1eec728fedf0e0c27b55c505)
|
|
||||||
- [Ubuntu bug #996950](https://bugs.launchpad.net/ubuntu/+source/supybot/+bug/996950)
|
|
||||||
- [Debian bug 672215](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=672215)
|
|
||||||
|
|
||||||
### 3. Anyone can access network services via the bot.
|
|
||||||
|
|
||||||
I don't have example command for this, but it happens by nesting "format cut"
|
|
||||||
and "misc tell".
|
|
||||||
|
|
||||||
What does this mean? Anyone can tell the bot to ghost someone else on same
|
|
||||||
account, take over a channel by telling the bot to give flags (if it has correct
|
|
||||||
flags), change password of the account and everything else what you do with
|
|
||||||
network services.
|
|
||||||
|
|
||||||
- _This was only reported at IRC and I am unable to find issue report or fixing
|
|
||||||
commit. ~~Mikaela on 2015-01-04._
|
|
||||||
|
|
||||||
### 4. Web page with special characters in \<title\> can be used to send DCC/CTCP commands.
|
|
||||||
|
|
||||||
This doesn't mean only things like CTCP actions (also known as /me), but known
|
|
||||||
problems with old routers ( `FF ? DCC SEND “ff???f??????????????” 0 0 0` ) which
|
|
||||||
make them reconnect to the internet.
|
|
||||||
|
|
||||||
Usage:
|
|
||||||
|
|
||||||
- `!web title <malicious.page.here>`
|
|
||||||
- `!web fetch <malicious.page.here>`
|
|
||||||
|
|
||||||
_This was only reported at IRC and I am unable to find issue report or fixing
|
|
||||||
commit. ~~Mikaela on 2015-01-04._
|
|
||||||
|
|
||||||
### 5. Web Titlte/Fetch can be used for DoS
|
|
||||||
|
|
||||||
They are vulnerable to queries to servers which have custom headers which can
|
|
||||||
lead to DoS.
|
|
||||||
|
|
||||||
_This was only reported at IRC and I am unable to find issue report or fixing
|
|
||||||
commit. ~~Mikaela on 2015-01-04._
|
|
||||||
|
|
||||||
### 6. QuoteGrabs grab command also works in PM
|
|
||||||
|
|
||||||
and can grab private content such as `user register` or `user identify` or with
|
|
||||||
the case of owner possibly NickServ passwords and others not so nice things.
|
|
||||||
|
|
||||||
- _It appears this issue was only reported at IRC._
|
|
||||||
- Fixing commit:
|
|
||||||
[a3346343679f3bdf8c77d9efb5a2097e215d51df](https://github.com/ProgVal/Limnoria/commit/a3346343679f3bdf8c77d9efb5a2097e215d51df)
|
|
||||||
|
|
||||||
### Are these issues publicly known?
|
|
||||||
|
|
||||||
**Of course they are.** Issue reports are below the actual issues.
|
|
||||||
|
|
||||||
The first issue has been also used to take down some of
|
|
||||||
[Ubuntu IRC bots](https://wiki.ubuntu.com/IRC/Bots) several times. At least
|
|
||||||
UbotX (I don't remember the number) and meetingology.
|
|
||||||
|
|
||||||
Some of these issues are fixed in git repository, but most people aren't using
|
|
||||||
it. If you wish to start using it, please scroll down to installation
|
|
||||||
instructions lower this page even though [Limnoria] and [gribble] are more
|
|
||||||
recommended.
|
|
||||||
|
|
||||||
### How to avoid them?
|
|
||||||
|
|
||||||
You can add anticapability for these commands using `owner defaultcapability`,
|
|
||||||
but that is only a temporary solution. There can also be other issues.
|
|
||||||
|
|
||||||
There are also two active Supybot forks, known as [Limnoria] and [Gribble],
|
|
||||||
which are actively developed and have fixed these issues. If you want permanent
|
|
||||||
solution, you should install either of them.
|
|
||||||
|
|
||||||
## Possibly interesting links
|
|
||||||
|
|
||||||
- [Comparsion of commit activity between Limnoria, Gribble and Supybot](https://www.openhub.net/p/compare?project_0=Limnoria&project_1=Gribble%3A+Support+Bottie&project_2=Supybot).
|
|
||||||
- [Gribble's modifications to stock Supybot](https://sourceforge.net/p/gribble/wiki/Gribble_Project_Git_Repository/)
|
|
||||||
- [Limnoria's modifications to Gribble.](https://github.com/ProgVal/Limnoria/wiki/LGC)
|
|
||||||
- Features of Gribble are fully merged to Limnoria.
|
|
||||||
|
|
||||||
Your current botname.conf is **100% compatible with forks**.
|
|
||||||
|
|
||||||
[Join Supybot channels on LiberaChat!](ircs://irc.libera.chat:6697/#supybot,#gribble,#limnoria)
|
|
||||||
|
|
||||||
[Limnoria]: https://github.com/ProgVal/Limnoria
|
|
||||||
[Gribble]: http://github.com/nanotube/supybot_fixes
|
|
||||||
|
|
||||||
## Installing forks
|
|
||||||
|
|
||||||
_This section has been removed in order to not duplicate
|
|
||||||
[Limnoria's documentation.](http://doc.supybot.aperio.fr/en/latest/use/install.html)_
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Do you know issue that isn't mentioned here? If it's not already reported,
|
|
||||||
please report it
|
|
||||||
on [Limnoria's issue tracker.](https://github.com/ProgVal/Limnoria/issues) If
|
|
||||||
it's known, but just not reported here,
|
|
||||||
[please feel free to add it.](https://github.com/Mikaela/limnoria/edit/gh-pages/Supybot.markdown)
|
|
||||||
40
TODO
Normal file
40
TODO
Normal file
@ -0,0 +1,40 @@
|
|||||||
|
Roughly in order of precedence (the closer to the front of the file,
|
||||||
|
the more likely it'll be done before next release):
|
||||||
|
|
||||||
|
* We should have a channel-global value in ircdb.IrcChannel for
|
||||||
|
ignoring unregistered users.
|
||||||
|
|
||||||
|
* We need to note when bans expire on a channel and send the unban,
|
||||||
|
that way plugins can use the ircdb ban stuff and not worry about
|
||||||
|
sending or scheduling unbans.
|
||||||
|
|
||||||
|
* We should probably add a "hello" command to make things more
|
||||||
|
compatible with Eggdrop, since we've been replacing many eggdrop
|
||||||
|
bots lately.
|
||||||
|
|
||||||
|
* We should be able to set the log level for plugins individually.
|
||||||
|
|
||||||
|
* Rbot has a "remind" plugin that seems pretty cool, we should get
|
||||||
|
one as well. It might do well as a command in the Later plugin.
|
||||||
|
|
||||||
|
* MozBot has a "list" plugin that seems pretty cool, we should get
|
||||||
|
one as well.
|
||||||
|
|
||||||
|
Problems that involve a lot of tedious minutiae, but really need to
|
||||||
|
be done at some point:
|
||||||
|
|
||||||
|
Hard problems that won't get done until someone really wants to have
|
||||||
|
some fun:
|
||||||
|
|
||||||
|
* Redundant relaying -- having more than one bot handle relaying,
|
||||||
|
where a secondary one will automatically take over if the first
|
||||||
|
becomes incapacitated.
|
||||||
|
|
||||||
|
* Have the bot detect when other bots are in the channel responding
|
||||||
|
to the same prefix character, and do something based on that.
|
||||||
|
|
||||||
|
* Unicode support. Basically, we'd have to have a way to set the
|
||||||
|
encoding for the server, and use unicode throughout internally.
|
||||||
|
The real issue is how much it would affect the current code to
|
||||||
|
switch it over to unicode, and what kind of burden it would put on
|
||||||
|
plugin authors to deal with that issue.
|
||||||
38
_config.yml
38
_config.yml
@ -1,38 +0,0 @@
|
|||||||
# @format
|
|
||||||
|
|
||||||
theme: minima
|
|
||||||
title: Mikaela's Supybot site
|
|
||||||
tagline: Things official documentation may not tell you
|
|
||||||
author:
|
|
||||||
name: "Aminda Suomalainen"
|
|
||||||
url: "https://aminda.eu/"
|
|
||||||
description: > # this means to ignore newlines until "baseurl:"
|
|
||||||
Mikaela's Supybot site where nowadays the only content is security issues of
|
|
||||||
stock Supybot.
|
|
||||||
baseurl: "" # the subpath of your site, e.g. /blog/
|
|
||||||
url: "https://supybot.mikaela.info/" # the base hostname & protocol for your site
|
|
||||||
github_username: Mikaela
|
|
||||||
lang: en
|
|
||||||
timezone: Etc/UTC
|
|
||||||
encoding: utf-8
|
|
||||||
plugins:
|
|
||||||
# - jekyll-mentions
|
|
||||||
- jekyll-redirect-from
|
|
||||||
- jekyll-sitemap
|
|
||||||
- jekyll-seo-tag
|
|
||||||
sitemap:
|
|
||||||
file: "/sitemap.xml"
|
|
||||||
include: [robots.txt]
|
|
||||||
robots: nofollow, noai
|
|
||||||
icon: https://github.com/ProgVal/Supybot-website/raw/master/static/logo.png
|
|
||||||
markdown: kramdown
|
|
||||||
kramdown:
|
|
||||||
parse_block_html: true
|
|
||||||
#webmaster_verifications:
|
|
||||||
#google:
|
|
||||||
#bing:
|
|
||||||
defaults:
|
|
||||||
- scope:
|
|
||||||
path: "*"
|
|
||||||
values:
|
|
||||||
image: https://github.com/ProgVal/Supybot-website/raw/master/static/logo.png
|
|
||||||
@ -1,32 +0,0 @@
|
|||||||
<footer class="site-footer h-card">
|
|
||||||
<data class="u-url" href="{{ "/" | relative_url }}"></data>
|
|
||||||
|
|
||||||
<div class="wrapper">
|
|
||||||
|
|
||||||
<h2 class="footer-heading">{{ site.title | escape }}</h2>
|
|
||||||
|
|
||||||
<div class="footer-col-wrapper">
|
|
||||||
<div class="footer-col footer-col-1">
|
|
||||||
<ul class="contact-list">
|
|
||||||
<li class="p-name">
|
|
||||||
<a rel="me prefetch" href="{{ site.author.url }}">{{ site.author.name }}</a><br>
|
|
||||||
{{ site.title | escape }}
|
|
||||||
</li>
|
|
||||||
{%- if site.email -%}
|
|
||||||
<li><a class="u-email" href="mailto:{{ site.email }}">{{ site.email }}</a></li>
|
|
||||||
{%- endif -%}
|
|
||||||
</ul>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
<div class="footer-col footer-col-2">
|
|
||||||
{%- include social.html -%}
|
|
||||||
</div>
|
|
||||||
|
|
||||||
<div class="footer-col footer-col-3">
|
|
||||||
<p>{{- site.description | escape -}}</p>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
</footer>
|
|
||||||
@ -1,15 +0,0 @@
|
|||||||
<head>
|
|
||||||
<meta charset="utf-8">
|
|
||||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
||||||
<!---->
|
|
||||||
{%- seo -%}
|
|
||||||
<!---->
|
|
||||||
<meta name="robots" content="{% if page.robots %}{{ page.robots }} {% else %}{{ site.robots }} {% endif %}">
|
|
||||||
<link rel="icon" href="https://github.com/ProgVal/Supybot-website/raw/master/static/logo.png">
|
|
||||||
<meta name="color-scheme" content="dark light">
|
|
||||||
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#ffb700">
|
|
||||||
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#fdfdfd">
|
|
||||||
<link rel="stylesheet" href="{{ "/assets/main.css" | prepend: site.baseurl }}">
|
|
||||||
<link rel="alternate" type="application/rss+xml" title="{{ site.title }}" href="{{ "/feed.xml" | prepend: site.baseurl | prepend: site.url }}">
|
|
||||||
</head>
|
|
||||||
210
_sass/_base.scss
210
_sass/_base.scss
@ -1,210 +0,0 @@
|
|||||||
:root {
|
|
||||||
color-scheme: dark light;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Reset some basic elements
|
|
||||||
*/
|
|
||||||
body, h1, h2, h3, h4, h5, h6,
|
|
||||||
p, blockquote, pre, hr,
|
|
||||||
dl, dd, ol, ul, figure {
|
|
||||||
margin: 0;
|
|
||||||
padding: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Basic styling
|
|
||||||
*/
|
|
||||||
body {
|
|
||||||
font-family: $base-font-family;
|
|
||||||
font-size: $base-font-size;
|
|
||||||
line-height: $base-line-height;
|
|
||||||
font-weight: 300;
|
|
||||||
color: $text-color;
|
|
||||||
background-color: $background-color;
|
|
||||||
-webkit-text-size-adjust: 100%;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Set `margin-bottom` to maintain vertical rhythm
|
|
||||||
*/
|
|
||||||
h1, h2, h3, h4, h5, h6,
|
|
||||||
p, blockquote, pre,
|
|
||||||
ul, ol, dl, figure,
|
|
||||||
%vertical-rhythm {
|
|
||||||
margin-bottom: $spacing-unit / 2;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Images
|
|
||||||
*/
|
|
||||||
img {
|
|
||||||
max-width: 100%;
|
|
||||||
vertical-align: middle;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Figures
|
|
||||||
*/
|
|
||||||
figure > img {
|
|
||||||
display: block;
|
|
||||||
}
|
|
||||||
|
|
||||||
figcaption {
|
|
||||||
font-size: $small-font-size;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Lists
|
|
||||||
*/
|
|
||||||
ul, ol {
|
|
||||||
margin-left: $spacing-unit;
|
|
||||||
}
|
|
||||||
|
|
||||||
li {
|
|
||||||
> ul,
|
|
||||||
> ol {
|
|
||||||
margin-bottom: 0;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Headings
|
|
||||||
*/
|
|
||||||
h1, h2, h3, h4, h5, h6 {
|
|
||||||
font-weight: 300;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Links
|
|
||||||
*/
|
|
||||||
a {
|
|
||||||
color: $brand-color;
|
|
||||||
//text-decoration: none;
|
|
||||||
text-decoration: underline;
|
|
||||||
|
|
||||||
&:visited {
|
|
||||||
//color: darken($brand-color, 15%);
|
|
||||||
}
|
|
||||||
|
|
||||||
&:hover {
|
|
||||||
color: $text-color;
|
|
||||||
//text-decoration: underline;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Blockquotes
|
|
||||||
*/
|
|
||||||
blockquote {
|
|
||||||
color: $grey-color;
|
|
||||||
border-left: 4px solid $grey-color-light;
|
|
||||||
padding-left: $spacing-unit / 2;
|
|
||||||
font-size: 18px;
|
|
||||||
letter-spacing: -1px;
|
|
||||||
font-style: italic;
|
|
||||||
|
|
||||||
> :last-child {
|
|
||||||
margin-bottom: 0;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Code formatting
|
|
||||||
*/
|
|
||||||
pre,
|
|
||||||
code {
|
|
||||||
font-family: $monospace-font-family;
|
|
||||||
font-size: 15px;
|
|
||||||
border: 1px solid; //$grey-color-light;
|
|
||||||
border-radius: 3px;
|
|
||||||
background-color: revert; //#eef;
|
|
||||||
}
|
|
||||||
|
|
||||||
code {
|
|
||||||
padding: 1px 5px;
|
|
||||||
}
|
|
||||||
|
|
||||||
pre {
|
|
||||||
padding: 8px 12px;
|
|
||||||
overflow-x: scroll;
|
|
||||||
|
|
||||||
> code {
|
|
||||||
border: 0;
|
|
||||||
padding-right: 0;
|
|
||||||
padding-left: 0;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Wrapper
|
|
||||||
*/
|
|
||||||
.wrapper {
|
|
||||||
max-width: -webkit-calc(#{$content-width} - (#{$spacing-unit} * 2));
|
|
||||||
max-width: calc(#{$content-width} - (#{$spacing-unit} * 2));
|
|
||||||
margin-right: auto;
|
|
||||||
margin-left: auto;
|
|
||||||
padding-right: $spacing-unit;
|
|
||||||
padding-left: $spacing-unit;
|
|
||||||
@extend %clearfix;
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
max-width: -webkit-calc(#{$content-width} - (#{$spacing-unit}));
|
|
||||||
max-width: calc(#{$content-width} - (#{$spacing-unit}));
|
|
||||||
padding-right: $spacing-unit / 2;
|
|
||||||
padding-left: $spacing-unit / 2;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Clearfix
|
|
||||||
*/
|
|
||||||
%clearfix {
|
|
||||||
|
|
||||||
&:after {
|
|
||||||
content: "";
|
|
||||||
display: table;
|
|
||||||
clear: both;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Icons
|
|
||||||
*/
|
|
||||||
.icon {
|
|
||||||
|
|
||||||
> svg {
|
|
||||||
display: inline-block;
|
|
||||||
width: 16px;
|
|
||||||
height: 16px;
|
|
||||||
vertical-align: middle;
|
|
||||||
|
|
||||||
path {
|
|
||||||
fill: $grey-color;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@ -1,236 +0,0 @@
|
|||||||
/**
|
|
||||||
* Site header
|
|
||||||
*/
|
|
||||||
.site-header {
|
|
||||||
border-top: 5px solid $grey-color-dark;
|
|
||||||
border-bottom: 1px solid $grey-color-light;
|
|
||||||
min-height: 56px;
|
|
||||||
|
|
||||||
// Positioning context for the mobile navigation icon
|
|
||||||
position: relative;
|
|
||||||
}
|
|
||||||
|
|
||||||
.site-title {
|
|
||||||
font-size: 26px;
|
|
||||||
line-height: 56px;
|
|
||||||
letter-spacing: -1px;
|
|
||||||
margin-bottom: 0;
|
|
||||||
float: left;
|
|
||||||
|
|
||||||
&,
|
|
||||||
&:visited {
|
|
||||||
color: $grey-color-dark;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
.site-nav {
|
|
||||||
float: right;
|
|
||||||
line-height: 56px;
|
|
||||||
|
|
||||||
.menu-icon {
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
|
|
||||||
.page-link {
|
|
||||||
color: $text-color;
|
|
||||||
line-height: $base-line-height;
|
|
||||||
|
|
||||||
// Gaps between nav items, but not on the first one
|
|
||||||
&:not(:first-child) {
|
|
||||||
margin-left: 20px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
@include media-query($on-palm) {
|
|
||||||
position: absolute;
|
|
||||||
top: 9px;
|
|
||||||
right: 30px;
|
|
||||||
background-color: $background-color;
|
|
||||||
border: 1px solid $grey-color-light;
|
|
||||||
border-radius: 5px;
|
|
||||||
text-align: right;
|
|
||||||
|
|
||||||
.menu-icon {
|
|
||||||
display: block;
|
|
||||||
float: right;
|
|
||||||
width: 36px;
|
|
||||||
height: 26px;
|
|
||||||
line-height: 0;
|
|
||||||
padding-top: 10px;
|
|
||||||
text-align: center;
|
|
||||||
|
|
||||||
> svg {
|
|
||||||
width: 18px;
|
|
||||||
height: 15px;
|
|
||||||
|
|
||||||
path {
|
|
||||||
fill: $grey-color-dark;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
.trigger {
|
|
||||||
clear: both;
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
|
|
||||||
&:hover .trigger {
|
|
||||||
display: block;
|
|
||||||
padding-bottom: 5px;
|
|
||||||
}
|
|
||||||
|
|
||||||
.page-link {
|
|
||||||
display: block;
|
|
||||||
padding: 5px 10px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Site footer
|
|
||||||
*/
|
|
||||||
.site-footer {
|
|
||||||
border-top: 1px solid $grey-color-light;
|
|
||||||
padding: $spacing-unit 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-heading {
|
|
||||||
font-size: 18px;
|
|
||||||
margin-bottom: $spacing-unit / 2;
|
|
||||||
}
|
|
||||||
|
|
||||||
.contact-list,
|
|
||||||
.social-media-list {
|
|
||||||
list-style: none;
|
|
||||||
margin-left: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col-wrapper {
|
|
||||||
font-size: 15px;
|
|
||||||
color: $grey-color;
|
|
||||||
margin-left: -$spacing-unit / 2;
|
|
||||||
@extend %clearfix;
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col {
|
|
||||||
float: left;
|
|
||||||
margin-bottom: $spacing-unit / 2;
|
|
||||||
padding-left: $spacing-unit / 2;
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col-1 {
|
|
||||||
width: -webkit-calc(35% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(35% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col-2 {
|
|
||||||
width: -webkit-calc(20% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(20% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col-3 {
|
|
||||||
width: -webkit-calc(45% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(45% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
.footer-col-1,
|
|
||||||
.footer-col-2 {
|
|
||||||
width: -webkit-calc(50% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(50% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
|
|
||||||
.footer-col-3 {
|
|
||||||
width: -webkit-calc(100% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(100% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
@include media-query($on-palm) {
|
|
||||||
.footer-col {
|
|
||||||
float: none;
|
|
||||||
width: -webkit-calc(100% - (#{$spacing-unit} / 2));
|
|
||||||
width: calc(100% - (#{$spacing-unit} / 2));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Page content
|
|
||||||
*/
|
|
||||||
.page-content {
|
|
||||||
padding: $spacing-unit 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.page-heading {
|
|
||||||
font-size: 20px;
|
|
||||||
}
|
|
||||||
|
|
||||||
.post-list {
|
|
||||||
margin-left: 0;
|
|
||||||
list-style: none;
|
|
||||||
|
|
||||||
> li {
|
|
||||||
margin-bottom: $spacing-unit;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
.post-meta {
|
|
||||||
font-size: $small-font-size;
|
|
||||||
color: $grey-color;
|
|
||||||
}
|
|
||||||
|
|
||||||
.post-link {
|
|
||||||
display: block;
|
|
||||||
font-size: 24px;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Posts
|
|
||||||
*/
|
|
||||||
.post-header {
|
|
||||||
margin-bottom: $spacing-unit;
|
|
||||||
}
|
|
||||||
|
|
||||||
.post-title {
|
|
||||||
font-size: 42px;
|
|
||||||
letter-spacing: -1px;
|
|
||||||
line-height: 1;
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
font-size: 36px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
.post-content {
|
|
||||||
margin-bottom: $spacing-unit;
|
|
||||||
|
|
||||||
h2 {
|
|
||||||
font-size: 32px;
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
font-size: 28px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
h3 {
|
|
||||||
font-size: 26px;
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
font-size: 22px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
h4 {
|
|
||||||
font-size: 20px;
|
|
||||||
|
|
||||||
@include media-query($on-laptop) {
|
|
||||||
font-size: 18px;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@ -1,67 +0,0 @@
|
|||||||
/**
|
|
||||||
* Syntax highlighting styles
|
|
||||||
*/
|
|
||||||
.highlight {
|
|
||||||
background: #fff;
|
|
||||||
@extend %vertical-rhythm;
|
|
||||||
|
|
||||||
.c { color: #998; font-style: italic } // Comment
|
|
||||||
.err { color: #a61717; background-color: #e3d2d2 } // Error
|
|
||||||
.k { font-weight: bold } // Keyword
|
|
||||||
.o { font-weight: bold } // Operator
|
|
||||||
.cm { color: #998; font-style: italic } // Comment.Multiline
|
|
||||||
.cp { color: #999; font-weight: bold } // Comment.Preproc
|
|
||||||
.c1 { color: #998; font-style: italic } // Comment.Single
|
|
||||||
.cs { color: #999; font-weight: bold; font-style: italic } // Comment.Special
|
|
||||||
.gd { color: #000; background-color: #fdd } // Generic.Deleted
|
|
||||||
.gd .x { color: #000; background-color: #faa } // Generic.Deleted.Specific
|
|
||||||
.ge { font-style: italic } // Generic.Emph
|
|
||||||
.gr { color: #a00 } // Generic.Error
|
|
||||||
.gh { color: #999 } // Generic.Heading
|
|
||||||
.gi { color: #000; background-color: #dfd } // Generic.Inserted
|
|
||||||
.gi .x { color: #000; background-color: #afa } // Generic.Inserted.Specific
|
|
||||||
.go { color: #888 } // Generic.Output
|
|
||||||
.gp { color: #555 } // Generic.Prompt
|
|
||||||
.gs { font-weight: bold } // Generic.Strong
|
|
||||||
.gu { color: #aaa } // Generic.Subheading
|
|
||||||
.gt { color: #a00 } // Generic.Traceback
|
|
||||||
.kc { font-weight: bold } // Keyword.Constant
|
|
||||||
.kd { font-weight: bold } // Keyword.Declaration
|
|
||||||
.kp { font-weight: bold } // Keyword.Pseudo
|
|
||||||
.kr { font-weight: bold } // Keyword.Reserved
|
|
||||||
.kt { color: #458; font-weight: bold } // Keyword.Type
|
|
||||||
.m { color: #099 } // Literal.Number
|
|
||||||
.s { color: #d14 } // Literal.String
|
|
||||||
.na { color: #008080 } // Name.Attribute
|
|
||||||
.nb { color: #0086B3 } // Name.Builtin
|
|
||||||
.nc { color: #458; font-weight: bold } // Name.Class
|
|
||||||
.no { color: #008080 } // Name.Constant
|
|
||||||
.ni { color: #800080 } // Name.Entity
|
|
||||||
.ne { color: #900; font-weight: bold } // Name.Exception
|
|
||||||
.nf { color: #900; font-weight: bold } // Name.Function
|
|
||||||
.nn { color: #555 } // Name.Namespace
|
|
||||||
.nt { color: #000080 } // Name.Tag
|
|
||||||
.nv { color: #008080 } // Name.Variable
|
|
||||||
.ow { font-weight: bold } // Operator.Word
|
|
||||||
.w { color: #bbb } // Text.Whitespace
|
|
||||||
.mf { color: #099 } // Literal.Number.Float
|
|
||||||
.mh { color: #099 } // Literal.Number.Hex
|
|
||||||
.mi { color: #099 } // Literal.Number.Integer
|
|
||||||
.mo { color: #099 } // Literal.Number.Oct
|
|
||||||
.sb { color: #d14 } // Literal.String.Backtick
|
|
||||||
.sc { color: #d14 } // Literal.String.Char
|
|
||||||
.sd { color: #d14 } // Literal.String.Doc
|
|
||||||
.s2 { color: #d14 } // Literal.String.Double
|
|
||||||
.se { color: #d14 } // Literal.String.Escape
|
|
||||||
.sh { color: #d14 } // Literal.String.Heredoc
|
|
||||||
.si { color: #d14 } // Literal.String.Interpol
|
|
||||||
.sx { color: #d14 } // Literal.String.Other
|
|
||||||
.sr { color: #009926 } // Literal.String.Regex
|
|
||||||
.s1 { color: #d14 } // Literal.String.Single
|
|
||||||
.ss { color: #990073 } // Literal.String.Symbol
|
|
||||||
.bp { color: #999 } // Name.Builtin.Pseudo
|
|
||||||
.vc { color: #008080 } // Name.Variable.Class
|
|
||||||
.vg { color: #008080 } // Name.Variable.Global
|
|
||||||
.vi { color: #008080 } // Name.Variable.Instance
|
|
||||||
.il { color: #099 } // Literal.Number.Integer.Long
|
|
||||||
}
|
|
||||||
145
assets/main.scss
145
assets/main.scss
@ -1,145 +0,0 @@
|
|||||||
---
|
|
||||||
# front-matter
|
|
||||||
---
|
|
||||||
|
|
||||||
@charset "utf-8";
|
|
||||||
|
|
||||||
// Font specifications. I keep changing my mind on what are the most pleasant
|
|
||||||
// fonts to my eyes, so I won't bother commenting them here.'
|
|
||||||
$serif-font-family:
|
|
||||||
ui-serif, "Roboto Serif", "Noto Serif", Tinos, serif, "Noto Emoji",
|
|
||||||
"Noto Color Emoji", "Segoe UI Emoji", emoji;
|
|
||||||
$sans-serif-font-family:
|
|
||||||
"Inclusive Sans", ui-sans-serif, "Roboto Flex", "Segoe UI Variable", Roboto,
|
|
||||||
"Noto Sans", Arimo, sans-serif, "Noto Emoji", "Noto Color Emoji",
|
|
||||||
"Segoe UI Emoji", emoji;
|
|
||||||
$monospace-font-family:
|
|
||||||
"Comic Shanns Mono", ui-monospace, "Roboto Mono", "Segoe UI Mono",
|
|
||||||
"Noto Mono", Cousine, monospace, "Noto Emoji", "Noto Color Emoji",
|
|
||||||
"Segoe UI Emoji", emoji;
|
|
||||||
// Must be in the end under threat of undefined variable error.
|
|
||||||
$base-font-family: $sans-serif-font-family;
|
|
||||||
|
|
||||||
@font-face {
|
|
||||||
font-family: "Inclusive Sans";
|
|
||||||
src: url("https://raw.githubusercontent.com/LivKing/Inclusive-Sans/refs/heads/main/fonts/webfonts/InclusiveSans[wght].woff2")
|
|
||||||
format("woff2");
|
|
||||||
font-weight: normal;
|
|
||||||
font-style: normal;
|
|
||||||
}
|
|
||||||
@font-face {
|
|
||||||
font-family: "Inclusive Sans Italic";
|
|
||||||
src: url("https://raw.githubusercontent.com/LivKing/Inclusive-Sans/refs/heads/main/fonts/webfonts/InclusiveSans-Italic[wght].woff2")
|
|
||||||
format("woff2");
|
|
||||||
font-weight: normal;
|
|
||||||
font-style: italic;
|
|
||||||
}
|
|
||||||
@font-face {
|
|
||||||
font-family: "Comic Shanns Mono";
|
|
||||||
src: url("https://raw.githubusercontent.com/jesusmgg/comic-shanns-mono/refs/heads/master/fonts/ComicShannsMono-Regular.otf")
|
|
||||||
format("opentype");
|
|
||||||
}
|
|
||||||
|
|
||||||
@import "{{ site.theme }}";
|
|
||||||
|
|
||||||
:root {
|
|
||||||
color-scheme: dark light !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
* {
|
|
||||||
// box-sizing: border-box !important;
|
|
||||||
color: revert !important;
|
|
||||||
background-color: revert !important;
|
|
||||||
//margin: auto !important;
|
|
||||||
// line-height: 1.2 !important;
|
|
||||||
// A4 paper
|
|
||||||
//max-width: 210mm !important;
|
|
||||||
font-size: revert;
|
|
||||||
//padding: auto !important;
|
|
||||||
overflow-wrap: break-word !important;
|
|
||||||
hyphens: auto !important;
|
|
||||||
// Experimental trick to make all emojis text if supported.
|
|
||||||
//font-variant-emoji: text;
|
|
||||||
/* WCAG minimum suggestions */
|
|
||||||
margin-bottom: 2 !important;
|
|
||||||
line-height: 1.5 !important;
|
|
||||||
letter-spacing: 0.12 !important;
|
|
||||||
word-spacing: 0.16 !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
a {
|
|
||||||
text-decoration: underline !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
a.site-title {
|
|
||||||
font-family: $serif-font-family;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Monospace preferred for code
|
|
||||||
code,
|
|
||||||
pre {
|
|
||||||
font-family: $monospace-font-family !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
// So it will not look bigger than normal text
|
|
||||||
code {
|
|
||||||
font-size: 0.8em !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Sans-Serif for headings to constrast with aminda.eu
|
|
||||||
// h2,
|
|
||||||
// h3,
|
|
||||||
// h4,
|
|
||||||
// h5,
|
|
||||||
// h6 {
|
|
||||||
// font-family: $sans-serif-font-family !important;
|
|
||||||
// }
|
|
||||||
|
|
||||||
h2.footer-heading {
|
|
||||||
font-family: $sans-serif-font-family !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
// The introduction on top
|
|
||||||
#bio {
|
|
||||||
text-align: center;
|
|
||||||
font-style: italic;
|
|
||||||
font-family: ui-cursive, $sans-serif-font-family;
|
|
||||||
}
|
|
||||||
|
|
||||||
img {
|
|
||||||
border-radius: 50% !important;
|
|
||||||
display: block;
|
|
||||||
margin-left: auto !important;
|
|
||||||
margin-right: auto !important;
|
|
||||||
@media (min-width: 395px) {
|
|
||||||
display: float !important;
|
|
||||||
float: right !important;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
ul.linklist {
|
|
||||||
list-style: none inside;
|
|
||||||
font-family: $monospace-font-family;
|
|
||||||
//font-variant: small-caps;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Customize the dark theme to be more me
|
|
||||||
@media (prefers-color-scheme: dark) {
|
|
||||||
* {
|
|
||||||
color: #ffb700 !important;
|
|
||||||
border-color: #ffb700 !important;
|
|
||||||
background-color: #000000 !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
.site-nav {
|
|
||||||
color-scheme: only dark !important;
|
|
||||||
color: #ffb700 !important;
|
|
||||||
background-color: #000000 !important;
|
|
||||||
color: #ffb700 !important;
|
|
||||||
}
|
|
||||||
|
|
||||||
// I don't want links to be restored to amber'
|
|
||||||
a {
|
|
||||||
color: revert !important;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
63
debian/changelog
vendored
Normal file
63
debian/changelog
vendored
Normal file
@ -0,0 +1,63 @@
|
|||||||
|
supybot (0.79.9999+0.80.0pre2-1) unstable; urgency=high
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
* Urgency high because it still fixes previous bugs.
|
||||||
|
|
||||||
|
-- James Vega <vega.james@gmail.com> Fri, 17 Sep 2004 11:18:43 -0400
|
||||||
|
|
||||||
|
supybot (0.79.9999-1) unstable; urgency=high
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
* Urgency high because it still fixes previous bugs.
|
||||||
|
|
||||||
|
-- James Vega <vega.james@gmail.com> Mon, 6 Sep 2004 15:40:13 -0400
|
||||||
|
|
||||||
|
supybot (0.79.999-1) unstable; urgency=high
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
* Urgency high because of a bug in the Ebay plugin that would hang
|
||||||
|
the bot.
|
||||||
|
|
||||||
|
-- James Vega <vega.james@gmail.com> Tue, 31 Aug 2004 21:58:59 -0400
|
||||||
|
|
||||||
|
supybot (0.79.99-1) unstable; urgency=high
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
* Urgency high as 0.79.9 had a serious bug in src/callbacks.py
|
||||||
|
* Added a watch file
|
||||||
|
|
||||||
|
-- James Vega <vega.james@gmail.com> Mon, 30 Aug 2004 09:20:48 -0400
|
||||||
|
|
||||||
|
supybot (0.79.9-1) unstable; urgency=high
|
||||||
|
|
||||||
|
* New upstream (Closes: #268311)
|
||||||
|
* New maintainer: James Vega <vega.james@gmail.com>
|
||||||
|
* Urgency high to get the RC fix into Sarge (hopefully)
|
||||||
|
* debian/control:
|
||||||
|
+ Downgrade Recommends: python-sqlite to Suggests: python-sqlite
|
||||||
|
+ Update Build-Depends: cdbs, debhelper (>= 4.1.67)
|
||||||
|
+ Bump Standard-Version to 3.6.1.0, no changes necessary
|
||||||
|
* Convert to cdbs
|
||||||
|
|
||||||
|
-- James Vega <vega.james@gmail.com> Thu, 26 Aug 2004 17:28:03 -0400
|
||||||
|
|
||||||
|
supybot (0.77.2-1) unstable; urgency=low
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
|
||||||
|
-- Jonathan Hseu <vomjom@debian.org> Sun, 18 Apr 2004 02:58:25 -0500
|
||||||
|
|
||||||
|
supybot (0.77.1-1) unstable; urgency=low
|
||||||
|
|
||||||
|
* New upstream
|
||||||
|
* Add python-dev as a build-dep (closes: Bug#242953)
|
||||||
|
|
||||||
|
-- Jonathan Hseu <vomjom@debian.org> Sat, 10 Apr 2004 13:06:38 -0500
|
||||||
|
|
||||||
|
supybot (0.77.0-1) unstable; urgency=low
|
||||||
|
|
||||||
|
* Initial Release.
|
||||||
|
* Paste LICENSE file into copyright
|
||||||
|
|
||||||
|
-- Jonathan Hseu <vomjom@debian.org> Tue, 10 Mar 2004 00:59:46 -0600
|
||||||
|
|
||||||
1
debian/compat
vendored
Normal file
1
debian/compat
vendored
Normal file
@ -0,0 +1 @@
|
|||||||
|
4
|
||||||
21
debian/control
vendored
Normal file
21
debian/control
vendored
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
Source: supybot
|
||||||
|
Section: net
|
||||||
|
Priority: optional
|
||||||
|
Maintainer: James Vega <vega.james@gmail.com>
|
||||||
|
Build-Depends: debhelper (>= 4.1.67), cdbs, python (>= 2.3), python-dev (>= 2.3)
|
||||||
|
Standards-Version: 3.6.1.0
|
||||||
|
|
||||||
|
Package: supybot
|
||||||
|
Architecture: all
|
||||||
|
Depends: ${python:Depends}
|
||||||
|
Suggests: python-twisted, python-sqlite
|
||||||
|
Description: robust and user friendly Python IRC bot
|
||||||
|
Supybot is a robust (it doesn't crash), user friendly (it's easy
|
||||||
|
to configure) and programmer friendly (plugins are *extremely*
|
||||||
|
easy to write) Python IRC bot. It aims to be an adequate
|
||||||
|
replacement for most existing IRC bots. It includes a very
|
||||||
|
flexible and powerful ACL system for controlling access to
|
||||||
|
commands, as well as more than 50 builtin plugins providing
|
||||||
|
around 400 actual commands.
|
||||||
|
.
|
||||||
|
Homepage: http://supybot.sourceforge.net/
|
||||||
53
debian/copyright
vendored
Normal file
53
debian/copyright
vendored
Normal file
@ -0,0 +1,53 @@
|
|||||||
|
This package was debianized by Jonathan Hseu <vomjom@debian.org> on
|
||||||
|
Tue, 3 Feb 2004 21:45:46 -0600.
|
||||||
|
|
||||||
|
It was downloaded from http://supybot.sourceforge.net/
|
||||||
|
|
||||||
|
Upstream Authors:
|
||||||
|
|
||||||
|
/usr/share/doc/supybot/DEVS includes the names and descriptions of the
|
||||||
|
developers.
|
||||||
|
|
||||||
|
Copyright:
|
||||||
|
|
||||||
|
Files located in /usr/lib/python2.3/site-packages/supybot/others/ have their
|
||||||
|
own respective licenses, which are either commented at the top of the file, or
|
||||||
|
are held in the __license__ variable.
|
||||||
|
|
||||||
|
The licenses in that directory are either:
|
||||||
|
BSD-style, GPL, or the Python License
|
||||||
|
The first two can be found in /usr/share/common-licenses/
|
||||||
|
|
||||||
|
The Python License can be found in:
|
||||||
|
/usr/share/doc/python/copyright
|
||||||
|
|
||||||
|
The copyright for all other files are as follows (BSD-style):
|
||||||
|
|
||||||
|
Copyright (c) 2002, 2003, 2004 Jeremiah Fincher
|
||||||
|
All rights reserved.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without
|
||||||
|
modification, are permitted provided that the following conditions are met:
|
||||||
|
|
||||||
|
* Redistributions of source code must retain the above copyright notice,
|
||||||
|
this list of conditions, and the following disclaimer.
|
||||||
|
* Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
this list of conditions, and the following disclaimer in the
|
||||||
|
documentation and/or other materials provided with the distribution.
|
||||||
|
* Neither the name of the author of this software nor the name of
|
||||||
|
contributors to this software may be used to endorse or promote products
|
||||||
|
derived from this software without specific prior written permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||||
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||||
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||||
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
|
||||||
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||||
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||||
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||||
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||||
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
|
||||||
|
Portions of the included source code are copyright by its original author(s)
|
||||||
|
and remains subject to its associated license.
|
||||||
15
debian/docs
vendored
Normal file
15
debian/docs
vendored
Normal file
@ -0,0 +1,15 @@
|
|||||||
|
ACKS
|
||||||
|
BUGS
|
||||||
|
DEVS
|
||||||
|
README
|
||||||
|
RELNOTES
|
||||||
|
TODO
|
||||||
|
docs/CAPABILITIES
|
||||||
|
docs/CONFIGURATION
|
||||||
|
docs/FAQ
|
||||||
|
docs/GETTING_STARTED
|
||||||
|
docs/HACKING
|
||||||
|
docs/INTERFACES
|
||||||
|
docs/OVERVIEW
|
||||||
|
docs/PLUGIN-EXAMPLE
|
||||||
|
docs/STYLE
|
||||||
6
debian/rules
vendored
Executable file
6
debian/rules
vendored
Executable file
@ -0,0 +1,6 @@
|
|||||||
|
#!/usr/bin/make -f
|
||||||
|
include /usr/share/cdbs/1/rules/debhelper.mk
|
||||||
|
include /usr/share/cdbs/1/class/python-distutils.mk
|
||||||
|
|
||||||
|
DEB_INSTALL_MANPAGES_supybot := docs/man/supybot-adduser.1 docs/man/supybot-newplugin.1\
|
||||||
|
docs/man/supybot.1 docs/man/supybot-wizard.1
|
||||||
6
debian/watch
vendored
Normal file
6
debian/watch
vendored
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
# Example watch control file for uscan
|
||||||
|
# Rename this file to "watch" and then you can run the "uscan" command
|
||||||
|
# to check for upstream updates and more.
|
||||||
|
# Site Directory Pattern Version Script
|
||||||
|
version=2
|
||||||
|
http://osdn.dl.sourceforge.net/supybot/Supybot-(\d.\d\d.\d+(.\d+)?)\.tar\.gz
|
||||||
118
docs/CAPABILITIES
Normal file
118
docs/CAPABILITIES
Normal file
@ -0,0 +1,118 @@
|
|||||||
|
Ok, some explanation of the capabilities system is probably in
|
||||||
|
order. With most IRC bots (including the ones I've written myself
|
||||||
|
prior to this one) "what a user can do" is set in one of two ways. On
|
||||||
|
the *really* simple bots, each user has a numeric "level" and commands
|
||||||
|
check to see if a user has a "high enough level" to perform some
|
||||||
|
operation. On bots that are slightly more complicated, users have a
|
||||||
|
list of "flags" whose meanings are hardcoded, and the bot checks to
|
||||||
|
see if a user possesses the necessary flag before performing some
|
||||||
|
operation. Both methods, IMO, are rather arbitrary, and force the
|
||||||
|
user and the programmer to be unduly confined to less expressive
|
||||||
|
constructs.
|
||||||
|
|
||||||
|
This bot is different. Every user has a set of "capabilities" that is
|
||||||
|
consulted every time they give the bot a command. Commands, rather
|
||||||
|
than checking for a user level of 100, or checking if the user has an
|
||||||
|
"o" flag, are instead able to check if a user has the "owner"
|
||||||
|
capability. At this point such a difference might not seem
|
||||||
|
revolutionary, but at least we can already tell that this method is
|
||||||
|
self-documenting, and easier for users and developers to understand
|
||||||
|
what's truly going on.
|
||||||
|
|
||||||
|
If that was all, well, the capability system would be "cool", but not
|
||||||
|
many people would say it was "awesome". But it *is* awesome! Several
|
||||||
|
things are happening behind the scene that make it awesome, and these
|
||||||
|
are things that couldn't happen if the bot was using numeric
|
||||||
|
userlevels or single-character flags. First, whenever a user issues
|
||||||
|
the bot a command, the command dispatcher checks to make sure the user
|
||||||
|
doesn't have the "anticapability" for that command. An anticapability
|
||||||
|
is a capability that, instead of saying "what a user can do", says
|
||||||
|
what a user *cannot* do. It's formed rather simply by adding a dash
|
||||||
|
("-") to the beginning of a capability; "rot13" is a capability, and
|
||||||
|
"-rot13" is an anticapability. Anyway, when a user issues the bot a
|
||||||
|
command, perhaps "calc" or "help", the bot first checks to make sure
|
||||||
|
the user doesn't have the "-calc" or the "-help" capabilities before
|
||||||
|
even considering responding to the user. So commands can be turned on
|
||||||
|
or off on a *per user* basis, offering fine-grained control not often
|
||||||
|
(if at all!) seen in other bots.
|
||||||
|
|
||||||
|
But that's not all! The capabilities system also supports *Channel*
|
||||||
|
capabilities, which are capabilities that only apply to a specific
|
||||||
|
channel; they're of the form "#channel,capability". Whenever a user
|
||||||
|
issues a command to the bot in a channel, the command dispatcher also
|
||||||
|
checks to make sure the user doesn't have the anticapability for that
|
||||||
|
command *in that channel*, and if the user does, the bot won't respond
|
||||||
|
to the user in the channel. Thus now, in addition to having the
|
||||||
|
ability to turn individual commands on or off for an individual user,
|
||||||
|
we can now turn commands on or off for an individual user on an
|
||||||
|
individual channel!
|
||||||
|
|
||||||
|
So when a user "foo" sends a command "bar" to the bot on channel
|
||||||
|
"#baz", first the bot checks to see if the user has the anticapability
|
||||||
|
for the command by itself, "-bar". If so, it returns right then and
|
||||||
|
there, completely ignoring the fact that the user issued that command
|
||||||
|
to it. If the user doesn't have that anticapability, then the bot
|
||||||
|
checks to see if the user issued the command over a channel, and if
|
||||||
|
so, checks to see if the user has the antichannelcapability for that
|
||||||
|
command, "#baz,-bar". If so, again, he returns right then and there
|
||||||
|
and doesn't even think about responding to the bot. If neither of
|
||||||
|
these anticapabilities are present, then the bot just responds to the
|
||||||
|
user like normal.
|
||||||
|
|
||||||
|
From a programming perspective, capabilties are easy to use and
|
||||||
|
flexible. Any command can check if a user has any capability, even
|
||||||
|
ones not thought of when the bot was originally written.
|
||||||
|
Commands/Callbacks can add their own capabilities -- it's as easy as
|
||||||
|
just checking for a capability and documenting somewhere that a user
|
||||||
|
needs that capability to do something.
|
||||||
|
|
||||||
|
From an end-user perspective, capabilities remove a lot of the mystery
|
||||||
|
and esotery of bot control, in addition to giving the user absolutely
|
||||||
|
finegrained control over what users are allowed to do with the bot.
|
||||||
|
Additionally, defaults can be set by the end-user for both individual
|
||||||
|
channels and for the bot as a whole, letting an end-user set the
|
||||||
|
policy he wants the bot to follow for users that haven't yet
|
||||||
|
registered in his user database. It's really a revolution!
|
||||||
|
|
||||||
|
There are several default capabilities the bot uses. The most
|
||||||
|
important of these is the "owner" capability. This capability allows
|
||||||
|
the person having it to use *any* command. It's best to keep this
|
||||||
|
capability reserved to people who actually have access to the shell
|
||||||
|
the bot is running on.
|
||||||
|
|
||||||
|
There is also the "admin" capability for non-owners that are highly
|
||||||
|
trusted to administer the bot appropriately. They can do things such
|
||||||
|
as change the bot's nick, globally enable/disable commands, cause the
|
||||||
|
bot to ignore a given user, set the prefixchar, report bugs, etc.
|
||||||
|
They generally cannot do administration related to channels, which is
|
||||||
|
reserved for people with the next capability.
|
||||||
|
|
||||||
|
People who are to administer channels with the bot should have the
|
||||||
|
#channel,op capability -- whatever channel they are to administrate,
|
||||||
|
they should have that channel capability for "op". For example, since
|
||||||
|
I want inkedmn to be an administrator in #supybot, I'll give him the
|
||||||
|
#supybot,op capability. This is in addition to his admin capability,
|
||||||
|
since the admin capability doesn't give the person having it control
|
||||||
|
over channels. #channel,op is used for such things as
|
||||||
|
giving/receiving ops, kickbanning people, lobotomizing the bot,
|
||||||
|
ignoring users in the channel, and managing the channel capabilities.
|
||||||
|
The #channel,op capability is also basically the equivalent of the
|
||||||
|
owner capability for capabilities involving #channel -- basically
|
||||||
|
anyone with the #channel,op capability is considered to have all
|
||||||
|
positive capabilities and no negative capabilities for #channel.
|
||||||
|
|
||||||
|
One other globally important capability exists: "trusted". This is a
|
||||||
|
command that basically says "This user can be trusted not to try and
|
||||||
|
crash the bot." It allows users to call commands like Math.icalc,
|
||||||
|
which potentially could cause the bot to begin a calculation that
|
||||||
|
could potentially never return (a calculation like 10**10**10**10).
|
||||||
|
Another command that requires the trusted capability is Utilties.re,
|
||||||
|
which (due to the regular expression implementation in Python (and any
|
||||||
|
other language that uses NFA regular expressions, like Perl or Ruby or
|
||||||
|
Lua or ...) which can allow a regular expression to take exponential
|
||||||
|
time to process). Consider what would happen if someone gave the
|
||||||
|
bot the command 're [format join "" s/./ [dict go] /] [dict go]'
|
||||||
|
|
||||||
|
Other plugins may require different capabilities; the Factoids plugin
|
||||||
|
requires #channel,factoids, the Topic plugin requires #channel,topic,
|
||||||
|
etc.
|
||||||
174
docs/CONFIGURATION
Normal file
174
docs/CONFIGURATION
Normal file
@ -0,0 +1,174 @@
|
|||||||
|
So you've got your Supybot up and running and there are some things
|
||||||
|
you don't like about it. Fortunately for you, chances are that these
|
||||||
|
things are configurable, and this document is here to tell you how to
|
||||||
|
configure them.
|
||||||
|
|
||||||
|
Configuration of Supybot is handled via the Config plugin, which
|
||||||
|
controls runtime access to Supybot's registry (the configuration file
|
||||||
|
generated by the supybot-wizard program you ran). The Config plugin
|
||||||
|
provides a way to get or set variables, to list the available
|
||||||
|
variables, and even to get help for certain variables. Take a moment
|
||||||
|
now to read the help for each of those commands: config, list, and
|
||||||
|
help. If you don't know how to get help on those commands, go ahead
|
||||||
|
and read our GETTING_STARTED document before this one.
|
||||||
|
|
||||||
|
Now, if you're used to the Windows registry, don't worry, Supybot's
|
||||||
|
registry is completely different. For one, it's completely plain
|
||||||
|
text. There's no binary database sensitive to corruption, it's not
|
||||||
|
necessary to use another program to edit it -- all you need is a
|
||||||
|
simple text editor. But there is at least one good idea in Windows'
|
||||||
|
registry: hierarchical configuration. Supybot's configuration
|
||||||
|
variables are organized in a hierarchy: variables having to do with
|
||||||
|
the way Supybot makes replies all start with supybot.reply; variables
|
||||||
|
having to do with the way a plugin works all start with
|
||||||
|
supybot.plugins.Plugin (where Plugin is the name of the plugin in
|
||||||
|
question). This hierarchy is nice because it means the user isn't
|
||||||
|
inundated with hundreds of unrelated and unsorted configuration
|
||||||
|
variables.
|
||||||
|
|
||||||
|
Some of the more important configuration values are located directly
|
||||||
|
under the base group, supybot. Things like the bot's nick, its ident,
|
||||||
|
etc. Along with these config values are a few subgroups that contain
|
||||||
|
other values. Some of the more prominent subgroups are: plugins
|
||||||
|
(where all the plugin-specific configuration is held), reply (where
|
||||||
|
variables affecting the way a Supybot makes its replies resides),
|
||||||
|
replies (where all the specific standard replies are kept), and
|
||||||
|
directories (where all the directories a Supybot uses are defined).
|
||||||
|
There are other subgroups as well, but these are the ones we'll use in
|
||||||
|
our example.
|
||||||
|
|
||||||
|
Using the Config plugin, you can list the values in a subgroup and get
|
||||||
|
or set any of the values anywhere in the configuration hierarchy. For
|
||||||
|
example, let's say you wanted to see what configuration values were
|
||||||
|
under the "supybot" (the base group) hierarchy. You would simply
|
||||||
|
issue this command:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config list supybot
|
||||||
|
<supybot> @capabilities, @commands, @databases, @debug, @directories, @drivers,
|
||||||
|
@log, @networks, @nick, @plugins, @protocols, @replies, @reply,
|
||||||
|
alwaysJoinOnInvite, channels, defaultIgnore, defaultSocketTimeout,
|
||||||
|
externalIP, flush, followIdentificationThroughNickChanges,
|
||||||
|
humanTimestampFormat, ident, pidFile, snarfThrottle, upkeepInterval,
|
||||||
|
and user
|
||||||
|
|
||||||
|
These are all the configuration groups and values which are under the
|
||||||
|
base "supybot" group. Actually, their full names would each have a
|
||||||
|
"supybot." appended on to the front of them, but it is omitted in the
|
||||||
|
listing in order to shorten the output. The first entries in the output are
|
||||||
|
the groups (distinguished by the @ symbol in front of them), and the rest are
|
||||||
|
the configuration values.
|
||||||
|
|
||||||
|
Okay, now that you've used the Config plugin to list configuration
|
||||||
|
variables, it's time that we start looking at individual variables and
|
||||||
|
their values.
|
||||||
|
|
||||||
|
The first (and perhaps most important) thing you should know about
|
||||||
|
each configuration variable is that they all have an associated help
|
||||||
|
string to tell you what they represent. So the first command we'll
|
||||||
|
cover is "config help". To see the help string for any value or
|
||||||
|
group, simply use the "config help" command. For example, to see what
|
||||||
|
this "supybot.snarfThrottle" configuration variable is all about, we'd
|
||||||
|
do this:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config help supybot.snarfThrottle
|
||||||
|
<supybot> jemfinch|lambda: A floating point number of seconds to throttle snarfed
|
||||||
|
URLs, in order to prevent loops between two bots snarfing the same URLs and
|
||||||
|
having the snarfed URL in the output of the snarf message. (Current value:
|
||||||
|
10.0)
|
||||||
|
|
||||||
|
Pretty simple, eh?
|
||||||
|
|
||||||
|
Now, if you're curious what the current value of a configuration
|
||||||
|
variable is, you'll use the "config" command with one argument, the
|
||||||
|
name of the variable you want to see the value of:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: '@'
|
||||||
|
|
||||||
|
To set this value, just stick an extra argument after the name:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
|
||||||
|
Now, check this out:
|
||||||
|
|
||||||
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: '@$'
|
||||||
|
|
||||||
|
Note that we used $ as our prefix character, and that the value of the
|
||||||
|
configuration variable changed. If I were to use the "flush" command
|
||||||
|
now, this change would be flushed to the registry file on disk (this
|
||||||
|
would also happen if I made the bot quit, or pressed Ctrl-C in the
|
||||||
|
terminal the bot was running in). Instead, I'll revert the change:
|
||||||
|
|
||||||
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars @
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> $note that this makes no response.
|
||||||
|
|
||||||
|
If you're ever curious what the default for a given configuration
|
||||||
|
variable is, use the "config default" command:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: ''
|
||||||
|
|
||||||
|
Thus, to reset a configuration variable to its default value, you can
|
||||||
|
simply say:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars [config
|
||||||
|
default supybot.reply.whenAddressedBy.chars]
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> @note that this does nothing
|
||||||
|
|
||||||
|
Simple, eh?
|
||||||
|
|
||||||
|
Now, let's say you want to find all configuration variables that might
|
||||||
|
be even remotely related to opping. For that, you'll want the "config
|
||||||
|
search" command. Check this out:
|
||||||
|
|
||||||
|
<jemfinch|lambda> @config search op
|
||||||
|
<supybot> jemfinch|lambda:
|
||||||
|
supybot.plugins.Enforcer.autoOp,
|
||||||
|
supybot.plugins.Enforcer.autoHalfop,
|
||||||
|
supybot.plugins.Enforcer.takeRevenge.onOps,
|
||||||
|
supybot.plugins.Enforcer.cycleToGetOps,
|
||||||
|
supybot.plugins.Topic, supybot.plugins.Topic.public,
|
||||||
|
supybot.plugins.Topic.separator,
|
||||||
|
supybot.plugins.Topic.format,
|
||||||
|
supybot.plugins.Topic.recognizeTopiclen,
|
||||||
|
supybot.plugins.Topic.default,
|
||||||
|
supybot.plugins.Topic.undo.maz, and
|
||||||
|
supybot.plugins.Relay.topicSync
|
||||||
|
|
||||||
|
Sure, it showed up all the topic-related stuff in there, but it also
|
||||||
|
showed you all the op-related stuff, too. Do note, however, that you
|
||||||
|
can only see configuration variables for plugins that you have loaded
|
||||||
|
or that you loaded in the past; if you've never loaded a plugin,
|
||||||
|
there's no way for the bot to know what configuration variables it
|
||||||
|
registers.
|
||||||
|
|
||||||
|
Some people might like editing their registry file directly rather
|
||||||
|
than manipulating all these things through the bot. For those people,
|
||||||
|
we offer the "config reload" command, which reloads both registry
|
||||||
|
configuration and user/channel/ignore database configuration. Just
|
||||||
|
edit the interesting files and then give the bot the "config reload"
|
||||||
|
command and it'll work as expected. Do note, however, that Supybot
|
||||||
|
flushes his configuration files and databases to disk every hour or
|
||||||
|
so, and if this happens after you've edited your configuration files
|
||||||
|
but before you reload your changes, you could lose the changes you
|
||||||
|
made. To prevent this, set the supybot.flush value to Off, and no
|
||||||
|
automatic flushing will occur.
|
||||||
|
|
||||||
|
Many configuration variables can be specific to individual channels.
|
||||||
|
The Config plugin provides an easy way to configure something for a
|
||||||
|
specific channel; for instance, in order to set the prefix chars for a
|
||||||
|
specific channel, do this in that channel:
|
||||||
|
|
||||||
|
config channel supybot.reply.whenAddressedBy.chars !
|
||||||
|
|
||||||
|
That'll set the prefix chars in the channel that message is sent in to
|
||||||
|
!. Voila, channel-specific values! Also, note that when using the
|
||||||
|
Config plugin's list command, channel-specific values are preceded by
|
||||||
|
a '#' character to indicate such.
|
||||||
|
|
||||||
|
Anyway, that's about it for configuration. Have fun, and enjoy your
|
||||||
|
configurable bot!
|
||||||
25
docs/DocBook/Makefile
Normal file
25
docs/DocBook/Makefile
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
JADE=/usr/bin/jade
|
||||||
|
JADETEX=/usr/bin/jadetex
|
||||||
|
DVIPDF=/usr/bin/dvipdfm
|
||||||
|
HTMLSTYLESHEET=/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/docbook.dsl
|
||||||
|
PRINTSTYLESHEET=/usr/share/sgml/docbook/stylesheet/dsssl/modular/print/docbook.dsl
|
||||||
|
|
||||||
|
html: example.sgml capabilities.sgml
|
||||||
|
$(JADE) -t xml -d $(HTMLSTYLESHEET) $<
|
||||||
|
|
||||||
|
example.dvi: example.sgml
|
||||||
|
$(JADE) -t tex -d $(PRINTSTYLESHEET) $<
|
||||||
|
$(JADETEX) $(addsuffix .tex, $(basename $<))
|
||||||
|
|
||||||
|
example.pdf: example.dvi
|
||||||
|
$(DVIPDF) -o $(addsuffix .pdf, $(basename $<)) $<
|
||||||
|
|
||||||
|
capabilities.dvi: capabilities.sgml
|
||||||
|
$(JADE) -t tex -d $(PRINTSTYLESHEET) $<
|
||||||
|
$(JADETEX) $(addsuffix .tex, $(basename $<))
|
||||||
|
|
||||||
|
capabilities.pdf: capabilities.dvi
|
||||||
|
$(DVIPDF) -o $(addsuffix .pdf, $(basename $<)) $<
|
||||||
|
|
||||||
|
clean:
|
||||||
|
rm -f *.html
|
||||||
177
docs/DocBook/README.DocBook
Normal file
177
docs/DocBook/README.DocBook
Normal file
@ -0,0 +1,177 @@
|
|||||||
|
The Official Supybot DocBook Metadocumentation
|
||||||
|
(or, How Does One SGML File Turn Into All Those Document Formats?)
|
||||||
|
|
||||||
|
Okay, though this isn't the case yet, ideally all of Supybot's documentation
|
||||||
|
can and will be done using DocBook and DocBook-related tools as well as a few
|
||||||
|
custom extensions that I've written.
|
||||||
|
|
||||||
|
- How does DocBook work?
|
||||||
|
First things first, you have to understand sort of how DocBook works in order
|
||||||
|
to figure out how our documentation gets generated from just one file. What
|
||||||
|
DocBook is, basically, is just a DTD (Document Type Definition). What that
|
||||||
|
means is that it simply specifies how a document can be structured and still be
|
||||||
|
considered a valid document by placing restrictions on what elements go where.
|
||||||
|
It's a popular DTD because it is structured very well and it's not only fairly
|
||||||
|
generic, but it also has nice elements that make documenting things (such as
|
||||||
|
supybot) rather easy. It focuses on structure and content instead of
|
||||||
|
presentation which is what makes it nice for writing things which are output
|
||||||
|
format agnostic.
|
||||||
|
|
||||||
|
So, let's say we've written a proper DocBook document, now what? Well, using
|
||||||
|
an output formatting tool and a stylesheet, you create whatever form of output
|
||||||
|
you want. What we use for producing the outptut is jade, and DocBook comes
|
||||||
|
with a few stylesheets that work with that tool to create output formats like
|
||||||
|
HTML and TeX. From the TeX file we produce a DVI (device independent) file
|
||||||
|
with latex, and from that we produce the print formats of our documents, like
|
||||||
|
PDF and Postscript using tools like dvips and dvipdfm.
|
||||||
|
|
||||||
|
- What extra stuff do we do?
|
||||||
|
Well, since our documents all have to do with an IRC bot, there are some very
|
||||||
|
common things that we talk about a lot that we might like to format specially.
|
||||||
|
For example, when we discuss a particular command for the bot we might like to
|
||||||
|
have that text appear slightly different to emphasize the fact that it is
|
||||||
|
special. So, for the commonly used items that weren't already covered by
|
||||||
|
DocBook's DTD, I added elements into a new DTD which just extends DocBook's
|
||||||
|
DTD. So now we have elements like <nick> and <channel> and <botcommand> that
|
||||||
|
we can use for our documentation.
|
||||||
|
|
||||||
|
Of course, now that we have used a DTD with more stuff in it (than DocBook),
|
||||||
|
the stylesheets that DocBook provides won't do any special formatting for those
|
||||||
|
new elements so we have to write new stylesheets as well. Once again I just
|
||||||
|
extended the existing ones with formatting instructions on how to treat the new
|
||||||
|
elements. So with this done, now our HTML and TeX (and whatever else) output
|
||||||
|
will be properly formatted.
|
||||||
|
|
||||||
|
- How do I make my own changes to the DTD and stylesheets?
|
||||||
|
Primarily, you don't :) Ask me (Strike) first about it, and I will generally
|
||||||
|
write them for you or explain a better way of doing things. This is especially
|
||||||
|
true for the DTD, because that must remain consistent everywhere we write/read
|
||||||
|
supybot docs based on it. The stylesheets are more lax and can be modified to
|
||||||
|
produce whatever kind of output you wish.
|
||||||
|
|
||||||
|
So, with that warning/reminder out of the way, here's how to modify each
|
||||||
|
anyway. This doesn't really assume any knowledge of how to write a DTD, nor is
|
||||||
|
it an exhaustive reference on writing one, so don't treat it as such. I'm
|
||||||
|
basically just going to explain how to add extra elements that will play well
|
||||||
|
with the DocBook DTD.
|
||||||
|
|
||||||
|
-- Adding an element to the DTD
|
||||||
|
If you've decided that there's a certain "thing" that's mentioned a lot in the
|
||||||
|
documentation and deserves classification (for potential special formatting),
|
||||||
|
you'll probably want to create a new element (or set of elements) for it. I'll
|
||||||
|
walk you through how I added the "nick" element to our DTD (though many/most of
|
||||||
|
the elements I added follow an identical process).
|
||||||
|
|
||||||
|
The very first thing you need to figure out is: where in my document does this
|
||||||
|
element "fit". That is to say, what elements should/can rightly contain this
|
||||||
|
particular one? In the case of the "nick" element, it's basically always an
|
||||||
|
inline-formatted deal that belongs in paragraphs for the most part. For those
|
||||||
|
of you scratching your heads at that last sentence, perhaps thinking "okay, so
|
||||||
|
how are we supposed to know what is relevant?" I say, "don't worry, I learned
|
||||||
|
by example as well." Basically, I just looked through the DocBook DTD and
|
||||||
|
figured out where things belong. Now, even if you don't know the DocBook DTD
|
||||||
|
front-to-back, you can still peruse it to figure out where your new element
|
||||||
|
belongs. Obviously, you should probably know *some* DocBook to figure out what
|
||||||
|
each element means, but luckily all of our docs have been converted to DocBook
|
||||||
|
and serve as nice examples of the usage of many elements :)
|
||||||
|
|
||||||
|
Now, to figure out where something like "nick" belongs. In many ways, a nick
|
||||||
|
is sort of like a variable name (at least in documentation usage). So, the
|
||||||
|
element I chose to base it off of was "varname". If you have the DocBook DTD
|
||||||
|
installed (as you should if you intend on making extensions to it), the varname
|
||||||
|
element definition is contained in the dbpoolx.mod filename (in Debian, it's
|
||||||
|
under /usr/share/sgml/docbook/dtd/4.2). How did I know this? Well, grep is
|
||||||
|
your friend and mine too, and dbpoolx is the only filename that shows up when
|
||||||
|
grepping for "varname" in the DocBook DTD directory. So, we open up dbpoolx.mod and search for varname. The first thing we find it in looks like this:
|
||||||
|
|
||||||
|
<!ENTITY % tech.char.class
|
||||||
|
"action|application
|
||||||
|
|classname|methodname|interfacename|exceptionname
|
||||||
|
|ooclass|oointerface|ooexception
|
||||||
|
|command|computeroutput
|
||||||
|
|database|email|envar|errorcode|errorname|errortype|errortext|filename
|
||||||
|
|function|guibutton|guiicon|guilabel|guimenu|guimenuitem
|
||||||
|
|guisubmenu|hardware|interface|keycap
|
||||||
|
|keycode|keycombo|keysym|literal|constant|markup|medialabel
|
||||||
|
|menuchoice|mousebutton|option|optional|parameter
|
||||||
|
|prompt|property|replaceable|returnvalue|sgmltag|structfield
|
||||||
|
|structname|symbol|systemitem|token|type|userinput|varname
|
||||||
|
%ebnf.inline.hook;
|
||||||
|
%local.tech.char.class;">
|
||||||
|
|
||||||
|
Hmm, this doesn't look like a definition of varname (to me, but I sort of
|
||||||
|
cheated by having read about DocBook before-hand ;)), but it will be important
|
||||||
|
to remember for later. Let's try and find the element definition for varname
|
||||||
|
(so, basically, let's look for the first line that starts with "<!ELEMENT ").
|
||||||
|
The first line I come up with when I search is:
|
||||||
|
|
||||||
|
<!ELEMENT varname %ho; (%smallcptr.char.mix;)*>
|
||||||
|
|
||||||
|
Rather than write a separate tutorial for interpreting DTDs, I found a good
|
||||||
|
SGML tutorial online that explains everything necessary to help you parse the
|
||||||
|
DocBook DTD to figure out what the varname element really is, as well as to
|
||||||
|
help you learn all the stuff necessary for what we will cover in creating our
|
||||||
|
new nick element. That tutorial is at
|
||||||
|
http://www.w3.org/TR/WD-html40-970708/intro/sgmltut.html#howtodtd (it's for
|
||||||
|
reading the HTML DTD, but it applies to any DTD).
|
||||||
|
|
||||||
|
So, now that we understand how to write/read things for a DTD, we arrive at the
|
||||||
|
time where we can write the actual definition of our "nick" element:
|
||||||
|
|
||||||
|
<!ELEMENT Nick - - ((%smallcptr.char.mix;)+)>
|
||||||
|
|
||||||
|
As we learned in the above tutorial, this means that we are creating an element
|
||||||
|
named "nick", which must have start and end tags, and is defined to contain one
|
||||||
|
or more of whatever is in "smallcptr.char.mix". And rather than hunt through
|
||||||
|
the DocBook DTD to figure out what that is, for now we'll just live with the
|
||||||
|
fact that whatever can go into a DocBook varname can go into our new nick
|
||||||
|
element. If you feel so inclined, feel free to try and define the content
|
||||||
|
model for nick to only include valid nick characters. It's perfectly doable,
|
||||||
|
and I'll probably do it at some point but I haven't yet.
|
||||||
|
|
||||||
|
Since we're extending the DocBook DTD, I also decided that it'd be nice to
|
||||||
|
follow the element creation conventions observed in their DTD, so there are a
|
||||||
|
few more lines associated with our new nick element. All of them are related
|
||||||
|
to the attributes of the element, and allowing for them to be extended by
|
||||||
|
external DTDs (much like we are doing, only we aren't changing attributes of
|
||||||
|
existing elements, just adding our own). The first one is:
|
||||||
|
|
||||||
|
<!ENTITY % local.nick.attrib "">
|
||||||
|
|
||||||
|
This basically defines an empty entity named local.nick.attrib which we will
|
||||||
|
include so that if anyone chooses to extend the nick attributes, all they have
|
||||||
|
to do is redefine local.nick.attrib.
|
||||||
|
|
||||||
|
<!ENTITY % nick.role.attrib "%role.attrib;">
|
||||||
|
|
||||||
|
To tell you the truth, I'm not entirely sure what this is for, but it follows the DocBook convention :)
|
||||||
|
|
||||||
|
<!ATTLIST Nick
|
||||||
|
%common.attrib;
|
||||||
|
%local.nick.attrib;
|
||||||
|
%nick.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
This is, of course, our attribute list for our nick element. It consists of
|
||||||
|
the two things we just defined as well as common.attrib which contains things
|
||||||
|
like "id" and whatnot which all DocBook elements are expected to have.
|
||||||
|
|
||||||
|
-- Extending the DocBook DTD to recognize new elements
|
||||||
|
So, that's all you need to define your new element. But, we're not done just
|
||||||
|
yet! We're almost there, we just need to make it so that it works with the
|
||||||
|
existing DocBook elements, otherwise it's no good to us. Since we defined our
|
||||||
|
element to esentially be the same as varname, it probably belongs at the same
|
||||||
|
place within the DocBook schema as varname. Do you remember when we had that
|
||||||
|
large entity definition that wasn't what we were looking for at the time though
|
||||||
|
I said it'd be important later? Well, later is now. So, what that line tells
|
||||||
|
us is what class of elements DocBook has varname in, which is
|
||||||
|
"tech.char.class". And thanks to the DocBook convention of defining a
|
||||||
|
local.<classname> entity that we can extend, all we have to do is redefine
|
||||||
|
local.tech.char.class to contain "nick", and we are done.
|
||||||
|
|
||||||
|
You may notice, however, that we don't actually put varname right into the
|
||||||
|
local.tech.char.class entity, but instead we create our own
|
||||||
|
supybot.tech.char.class class of elements that are supybot-specific (and are
|
||||||
|
the equivalent of DocBook's tech.char.class elements) and instead, put all of
|
||||||
|
those into the local.tech.char.class entity. Basically, we just go through one
|
||||||
|
more level of indirection.
|
||||||
221
docs/DocBook/capabilities.sgml
Normal file
221
docs/DocBook/capabilities.sgml
Normal file
@ -0,0 +1,221 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
|
||||||
|
<article>
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Supybot capabilities system explanation</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>18 Feb 2004</date>
|
||||||
|
<revremark>Initial Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.2</revnumber>
|
||||||
|
<date>04 Sep 2004</date>
|
||||||
|
<revremark>Update Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<sect1>
|
||||||
|
<title>Introduction</title>
|
||||||
|
<subtitle>
|
||||||
|
Supybot's capabilities overview and comparisons to other bots
|
||||||
|
</subtitle>
|
||||||
|
<para>
|
||||||
|
Ok, some some explanation of the capabilities system is probably
|
||||||
|
in order. With most IRC bots (including the ones I've written
|
||||||
|
myself prior to this one) “what a user can do” is set
|
||||||
|
in one of two ways. On the <emphasis>really</emphasis> simple
|
||||||
|
bots, each user has a numeric “level” and commands
|
||||||
|
check to see if a user has a “high enough level” to
|
||||||
|
perform some operation. On bots that are slightly more
|
||||||
|
complicated, users have a list of “flags” whose
|
||||||
|
meanings are hardcoded, and the bot checks to see if a user
|
||||||
|
possesses the necessary flag before performing some operation.
|
||||||
|
Both methods, IMO, are rather arbitrary, and force the user and
|
||||||
|
the programmer to be unduly confined to less expressive
|
||||||
|
constructs.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This bot is different. Every user has a set of
|
||||||
|
“capabilities” that is consulted every time they give
|
||||||
|
the bot a command. Commands, rather than checking for a user
|
||||||
|
level of 100, or checking if the user has an <varname>o</varname>
|
||||||
|
flag, are instead able to check if a user has the
|
||||||
|
<capability>owner</capability> capability. At this point such a
|
||||||
|
difference might not seem revolutionary, but at least we can
|
||||||
|
already tell that this method is self-documenting, and easier for
|
||||||
|
users and developers to understand what's truly going on.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>What sets supybot's capabilities apart</title>
|
||||||
|
<para>
|
||||||
|
If that was all, well, the capability system would be
|
||||||
|
“cool”, but not many people would say it was
|
||||||
|
“awesome”. But it <emphasis>is</emphasis> awesome!
|
||||||
|
Several things are happening behind the scene that make it
|
||||||
|
awesome, and these are things that couldn't happen if the bot was
|
||||||
|
using numeric userlevels or single-character flags. First,
|
||||||
|
whenever a user issues the bot a command, the command dispatcher
|
||||||
|
checks to make sure the user doesn't have the
|
||||||
|
“anticapability” for that command. An anticapability is
|
||||||
|
a capability that, instead of saying “what a user can
|
||||||
|
do”, says what a user <emphasis>cannot</emphasis> do. It's
|
||||||
|
formed rather simply by adding a dash (“-”) to the
|
||||||
|
beginning of a capability; <botcommand>rot13</botcommand> is a
|
||||||
|
capability, and <botcommand>-rot13</botcommand> is an
|
||||||
|
anticapability. Anyway, when a user issues the bot a command,
|
||||||
|
perhaps <botcommand>calc</botcommand> or
|
||||||
|
<botcommand>help</botcommand>, the bot first checks to make sure
|
||||||
|
the user doesn't have the <capability>-calc</capability> or the
|
||||||
|
<capability>-help</capability> capabilities before even
|
||||||
|
considering responding to the user. So commands can be turned on
|
||||||
|
or off on a <emphasis>per user</emphasis> basis, offering
|
||||||
|
finegrained control not often (if at all!) seen in other bots.
|
||||||
|
</para>
|
||||||
|
<sect2>
|
||||||
|
<title>Channel capabilities</title>
|
||||||
|
<para>
|
||||||
|
But that's not all! The capabilities system also supports
|
||||||
|
<emphasis>Channel</emphasis> capabilities, which are
|
||||||
|
capabilities that only apply to a specific channel; they're of
|
||||||
|
the form <capability>#channel,capability</capability>.
|
||||||
|
Whenever a user issues a command to the bot in a channel, the
|
||||||
|
command dispatcher also checks to make sure the user doesn't
|
||||||
|
have the anticapability for that command <emphasis>in that
|
||||||
|
channel</emphasis> and if the user does, the bot won't respond
|
||||||
|
to the user in the channel. Thus now, in addition to having
|
||||||
|
the ability to turn individual commands on or off for an
|
||||||
|
individual user, we can now turn commands on or off for an
|
||||||
|
individual user on an individual channel!
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So when a user <nick>foo</nick> sends a command
|
||||||
|
<botcommand>bar</botcommand> to the bot on channel
|
||||||
|
<channel>#baz</channel>, first the bot checks to see if the
|
||||||
|
user has the anticapability for the command by itself,
|
||||||
|
<capability>-bar</capability>. If so, it returns right then
|
||||||
|
and there, compltely ignoring the fact that the user issued
|
||||||
|
that command to it. If the user doesn't have that
|
||||||
|
anticapability, then the bot checks to see if the user issued
|
||||||
|
the command over a channel, and if so, checks to see if the
|
||||||
|
user has the antichannelcapability for that command,
|
||||||
|
<capability>#baz,-bar</capability>. If so, again, he returns
|
||||||
|
right then and there and doesn't even think about responding
|
||||||
|
to the bot. If neither of these anticapabilities are present,
|
||||||
|
then the bot just responds to the user like normal.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Motivations behind the capabilities system</title>
|
||||||
|
<sect2>
|
||||||
|
<title>A programmer's perspective</title>
|
||||||
|
<para>
|
||||||
|
From a programming perspective, capabilties are easy to use
|
||||||
|
and flexible. Any command can check if a user has any
|
||||||
|
capability, even ones not thought of when the bot was
|
||||||
|
originally written. Commands/Callbacks can add their own
|
||||||
|
capabilities – it's as easy as just checking for a
|
||||||
|
capability and documenting somewhere that a user needs that
|
||||||
|
capability to do something.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>An end-user's perspective</title>
|
||||||
|
<para>
|
||||||
|
From an end-user perspective, capabilities remove a lot of the
|
||||||
|
mystery and esotery of bot control, in addition to giving the
|
||||||
|
user absolutely finegrained control over what users are
|
||||||
|
allowed to do with the bot. Additionally, defaults can be set
|
||||||
|
by the end-user for both individual channels and for the bot
|
||||||
|
as a whole, letting an end-user set the policy he wants the
|
||||||
|
bot to follow for users that haven't yet registered in his
|
||||||
|
user database.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<para>
|
||||||
|
It's really a revolution!
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Hard-coded supybot capabilities</title>
|
||||||
|
<para>
|
||||||
|
There are several default capabilities the bot uses. The most
|
||||||
|
important of these is the <capability>owner</capability>
|
||||||
|
capability. This capability allows the person having it to use
|
||||||
|
<emphasis>any</emphasis> command. It's best to keep this
|
||||||
|
capability reserved to people who actually have access to the
|
||||||
|
shell the bot is running on.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
There is also the <capability>admin</capability> capability for
|
||||||
|
non-owners that are highly trusted to administer the bot
|
||||||
|
appropriately. They can do things such as change the bot's nick,
|
||||||
|
globally enable/disable commands, cause the bot to ignore a given
|
||||||
|
user, set the prefixchar, report bugs, etc. They generally cannot
|
||||||
|
do administration related to channels, which is reserved for
|
||||||
|
people with the next capability.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
People who are to administer channels with the bot should have the
|
||||||
|
<capability>#channel,op</capability> capability – whatever
|
||||||
|
channel they are to administrate, they should have that channel
|
||||||
|
capability for <capability>op</capability>. For example, since I
|
||||||
|
want <nick>inkedmn</nick> to be an administrator in
|
||||||
|
<channel>#supybot</channel>, I'll give him the
|
||||||
|
<capability>#supybot,op</capability> capability. This is in
|
||||||
|
addition to his <capability>admin</capability> capability, since
|
||||||
|
the <capability>admin</capability> capability doesn't give the
|
||||||
|
person having it control over channels.
|
||||||
|
<capability>#channel.op</capability> is used for such things as
|
||||||
|
giving/receiving ops, kickbanning people, lobotomizing the bot,
|
||||||
|
ignoring users in the channel, and managing the channel
|
||||||
|
capabilities. The <capability>#channel,op</capability> capability
|
||||||
|
is also basically the equivalent of the owner capability for
|
||||||
|
capabilities involving <channel>#channel</channel> –
|
||||||
|
basically anyone with the <capability>#channel,op</capability>
|
||||||
|
capability is considered to have all positive capabilities and no
|
||||||
|
negative capabilities for <channel>#channel</channel>.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
One other globally important capability exists:
|
||||||
|
<capability>trusted</capability>. This is a command that
|
||||||
|
basically says “This user can be trusted not to try and
|
||||||
|
crash the bot.” It allows users to call commands like
|
||||||
|
<botcommand>Math.icalc</botcommand>, which potentially could cause the
|
||||||
|
bot to begin a calculation that could potentially never return (a
|
||||||
|
calculation like 10**10**10**10). Another command that requires
|
||||||
|
the trusted capability is <botcommand>Utilties.re</botcommand>, which
|
||||||
|
(due to the regular expression implementation in Python (and any
|
||||||
|
other language that uses NFA regular expressions, like Perl or
|
||||||
|
Ruby or Lua or …) which can allow a regular expression to
|
||||||
|
take exponential time to process). Consider what would happen if
|
||||||
|
the someone gave the bot the command <literal>re [strjoin "" s/./
|
||||||
|
[dict go] /] [dict go]</literal>.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Other capabilities</title>
|
||||||
|
<para>
|
||||||
|
Other plugins may require different capabilities; the
|
||||||
|
<plugin>Factoids</plugin> plugin requires
|
||||||
|
<capability>#channel,factoids</capability>, the <plugin>Topic</plugin>
|
||||||
|
plugin requires <capability>#channel,topic</capability>, etc.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
|
||||||
316
docs/DocBook/configuration.sgml
Normal file
316
docs/DocBook/configuration.sgml
Normal file
@ -0,0 +1,316 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
|
||||||
|
<article>
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Supybot configuration system explanation</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>18 Feb 2004</date>
|
||||||
|
<revremark>Initial Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.2</revnumber>
|
||||||
|
<date>26 Feb 2004</date>
|
||||||
|
<revremark>Conversion to Supybot DTD</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.3</revnumber>
|
||||||
|
<date>4 Sep 2004</date>
|
||||||
|
<revremark>Update Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<sect1>
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
So you've got your Supybot up and running and there are some
|
||||||
|
things you don't like about it. Fortunately for you, chances are
|
||||||
|
that these things are configurable, and this document is here to
|
||||||
|
tell you how to configure them.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Configuration of Supybot is handled via the
|
||||||
|
<plugin>Config</plugin> plugin, which controls runtime access to
|
||||||
|
Supybot's registry (the configuration file generated by the
|
||||||
|
<script>supybot-wizard</script> program you ran). The
|
||||||
|
<plugin>Config</plugin> plugin provides a way to get or set
|
||||||
|
variables, to list the available variables, and even to get help
|
||||||
|
for certain variables. Take a moment now to read the help for
|
||||||
|
each of those commands: <botcommand>config</botcommand>,
|
||||||
|
<botcommand>list</botcommand>, and
|
||||||
|
<botcommand>help</botcommand>. If you don't know how to get help on
|
||||||
|
those commands, go ahead and read our
|
||||||
|
<filename>GETTING_STARTED</filename> document before this one.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Supybot's registry</title>
|
||||||
|
<para>
|
||||||
|
Now, if you're used to the Windows registry, don't worry,
|
||||||
|
Supybot's registry is completely different. For one, it's
|
||||||
|
completely plain text. There's no binary database sensitive to
|
||||||
|
corruption, it's not necessary to use another program to edit it
|
||||||
|
– all you need is a simple text editor. But there is at
|
||||||
|
least one good idea in Windows' registry: hierarchical
|
||||||
|
configuration. Supybot's configuration variables are organized in
|
||||||
|
a hierarchy: variables having to do with the way Supybot makes
|
||||||
|
replies all start with
|
||||||
|
<registrygroup>supybot.reply</registrygroup>; variables having to
|
||||||
|
do with the way a plugin works all start with
|
||||||
|
<registrygroup>supybot.plugins.Plugin</registrygroup> (where
|
||||||
|
<plugin>Plugin</plugin> is the name of the plugin in question).
|
||||||
|
This hierarchy is nice because it means the user isn't inundated
|
||||||
|
with hundreds of unrelated and unsorted configuration variables.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Some of the more important configuration values are located
|
||||||
|
directly under the base group,
|
||||||
|
<registrygroup>supybot</registrygroup>. Things like the bot's
|
||||||
|
nick, its ident, etc. Along with these config values are a few
|
||||||
|
subgroups that contain other values. Some of the more prominent
|
||||||
|
subgroups are: <registrygroup>plugins</registrygroup> (where all
|
||||||
|
the plugin-specific configuration is held),
|
||||||
|
<registrygroup>reply</registrygroup> (where variables affecting
|
||||||
|
the way a Supybot makes its replies resides),
|
||||||
|
<registrygroup>replies</registrygroup> (where all the specific
|
||||||
|
standard replies are kept), and
|
||||||
|
<registrygroup>directories</registrygroup> (where all the
|
||||||
|
directories a Supybot uses are defined). There are other
|
||||||
|
subgroups as well, but these are the ones we'll use in our
|
||||||
|
example.
|
||||||
|
</para>
|
||||||
|
<sect2>
|
||||||
|
<title>Config plugin commands</title>
|
||||||
|
<sect3>
|
||||||
|
<title>Listing registry contents</title>
|
||||||
|
<para>
|
||||||
|
Using the <plugin>Config</plugin> plugin, you can list
|
||||||
|
the values in a subgroup and get or set any of the values
|
||||||
|
anywhere in the configuration hierarchy. For example,
|
||||||
|
let's say you wanted to see what configuration values were
|
||||||
|
under the <registrygroup>supybot</registrygroup> (the base
|
||||||
|
group) hierarchy. You would simply issue this command:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config list supybot
|
||||||
|
<supybot> @capabilities, @commands, @databases, @debug, @directories, @drivers,
|
||||||
|
@log, @networks, @nick, @plugins, @protocols, @replies, @reply,
|
||||||
|
alwaysJoinOnInvite, channels, defaultIgnore, defaultSocketTimeout,
|
||||||
|
externalIP, flush, followIdentificationThroughNickChanges,
|
||||||
|
humanTimestampFormat, ident, pidFile, snarfThrottle, upkeepInterval,
|
||||||
|
and user
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
These are all the configuration groups and values which
|
||||||
|
are under the base <registrygroup>supybot</registrygroup>
|
||||||
|
group. Actually, their full names would each have a
|
||||||
|
“supybot.” appended on to the front of them,
|
||||||
|
but it is omitted in the listing in order to shorten the
|
||||||
|
output. The first entries in the output are the groups
|
||||||
|
(distinguished by the @ symbol in front of them), and the
|
||||||
|
rest are the configuration values.
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
<sect2>
|
||||||
|
<title>Supybot's registry</title>
|
||||||
|
<sect3>
|
||||||
|
<title>Dealing with registry values</title>
|
||||||
|
<para>
|
||||||
|
Okay, now that you've used the <plugin>Config</plugin>
|
||||||
|
plugin to list configuration variables, it's time that we
|
||||||
|
start looking at individual variables and their values.
|
||||||
|
</para>
|
||||||
|
<sect4>
|
||||||
|
<title>Built-in help for registry values</title>
|
||||||
|
<para>
|
||||||
|
The first (and perhaps most important) thing you
|
||||||
|
should know about each configuration variable is that
|
||||||
|
they all have an associated help string to tell you
|
||||||
|
what they represent. So the first command we'll cover
|
||||||
|
is <botcommand>config help</botcommand>. To see the
|
||||||
|
help string for any value or group, simply use the
|
||||||
|
<botcommand>config help</botcommand> command. For
|
||||||
|
example, to see what this
|
||||||
|
<registrygroup>supybot.snarfThrottle</registrygroup>
|
||||||
|
configuration variable is all about, we'd do this:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config help supybot.snarfThrottle
|
||||||
|
<supybot> jemfinch|lambda: A floating point number of seconds to throttle snarfed
|
||||||
|
URLs, in order to prevent loops between two bots snarfing the same URLs and
|
||||||
|
having the snarfed URL in the output of the snarf message. (Current value:
|
||||||
|
10.0)
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Pretty simple, eh?
|
||||||
|
</para>
|
||||||
|
</sect4>
|
||||||
|
<sect4>
|
||||||
|
<title>Getting/setting registry values</title>
|
||||||
|
<para>
|
||||||
|
Now, if you're curious what the current value of a
|
||||||
|
configuration variable is, you'll use the
|
||||||
|
<botcommand>config</botcommand> command with one
|
||||||
|
argument, the name of the variable you want to see the
|
||||||
|
value of:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: '@'
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
To set this value, just stick an extra argument after
|
||||||
|
the name:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Now, check this out:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: '@$'
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Note that we used <literal>$</literal> as our prefix
|
||||||
|
character, and that the value of the configuration
|
||||||
|
variable changed. If I were to use the
|
||||||
|
<botcommand>flush</botcommand> command now, this
|
||||||
|
change would be flushed to the registry file on disk
|
||||||
|
(this would also happen if I made the bot quit, or
|
||||||
|
pressed
|
||||||
|
<keycombo>
|
||||||
|
<keycap>Ctrl</keycap>
|
||||||
|
<keycap>C</keycap>
|
||||||
|
</keycombo>
|
||||||
|
in the terminal the bot was running in). Instead,
|
||||||
|
I'll revert the change:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars @
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> $note that this makes no response.
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
If you're ever curious what the default for a given
|
||||||
|
configuration variable is, use the <botcommand>config
|
||||||
|
default</botcommand> command:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
|
||||||
|
<supybot> jemfinch|lambda: ''
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Thus, to reset a configuration variable to its default
|
||||||
|
value, you can simply say:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars [config default
|
||||||
|
supybot.reply.whenAddressedBy.chars]
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> @note that this does nothing
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Simple, eh?
|
||||||
|
</para>
|
||||||
|
</sect4>
|
||||||
|
</sect3>
|
||||||
|
<sect3>
|
||||||
|
<title>Searching the registry</title>
|
||||||
|
<para>
|
||||||
|
Now, let's say you want to find all configuration
|
||||||
|
variables that might be even remotely related to opping.
|
||||||
|
For that, you'll want the <botcommand>config
|
||||||
|
search</botcommand> command. Check this out:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> @config search op
|
||||||
|
<supybot> jemfinch|lambda:
|
||||||
|
supybot.plugins.Enforcer.autoOp,
|
||||||
|
supybot.plugins.Enforcer.autoHalfop,
|
||||||
|
supybot.plugins.Enforcer.takeRevenge.onOps,
|
||||||
|
supybot.plugins.Enforcer.cycleToGetOps,
|
||||||
|
supybot.plugins.Topic, supybot.plugins.Topic.public,
|
||||||
|
supybot.plugins.Topic.separator,
|
||||||
|
supybot.plugins.Topic.format,
|
||||||
|
supybot.plugins.Topic.recognizeTopiclen,
|
||||||
|
supybot.plugins.Topic.default,
|
||||||
|
supybot.plugins.Topic.undo.maz, and
|
||||||
|
supybot.plugins.Relay.topicSync
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Sure, it showed up all the topic-related stuff in there,
|
||||||
|
but it also showed you all the op-related stuff, too. Do
|
||||||
|
note, however, that you can only see configuration
|
||||||
|
variables for plugins that you have loaded or that you
|
||||||
|
loaded in the past; if you've never loaded a plugin,
|
||||||
|
there's no way for the bot to know what configuration
|
||||||
|
variables it registers.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Some people might like editing their registry file
|
||||||
|
directly rather than manipulating all these things through
|
||||||
|
the bot. For those people, we offer the
|
||||||
|
<botcommand>config reload</botcommand> command, which
|
||||||
|
reloads both registry configuration and
|
||||||
|
user/channel/ignore database configuration. Just edit the
|
||||||
|
interesting files and then give the bot the
|
||||||
|
<botcommand>config reload</botcommand> command and it'll
|
||||||
|
work as expected. Do note, however, that Supybot flushes
|
||||||
|
his configuration files and databases to disk every hour
|
||||||
|
or so, and if this happens after you've edited your
|
||||||
|
configuration files but before you reload your changes,
|
||||||
|
you could lose the changes you made. To prevent this, set
|
||||||
|
the <registrygroup>supybot.flush</registrygroup> value to
|
||||||
|
<literal>Off</literal>, and no automatic flushing will
|
||||||
|
occur.
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
<sect3>
|
||||||
|
<title>Channel-specific configuration</title>
|
||||||
|
<para>
|
||||||
|
Many configuration variables can be specific to individual
|
||||||
|
channels. The <plugin>Config</plugin> plugin provides an
|
||||||
|
easy way to configure something for a specific channel;
|
||||||
|
for instance, in order to set the prefix chars for a
|
||||||
|
specific channel, do this in that channel:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
config channel supybot.reply.whenAddressedBy.chars !
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
That'll set the prefix chars in the channel that message
|
||||||
|
is sent in to <literal>!</literal>. Voila,
|
||||||
|
channel-specific values!
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>All done!</title>
|
||||||
|
<para>
|
||||||
|
Anyway, that's about it for configuration. Have fun, and enjoy
|
||||||
|
your configurable bot!
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
|
||||||
359
docs/DocBook/faq.sgml
Normal file
359
docs/DocBook/faq.sgml
Normal file
@ -0,0 +1,359 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
<article class="faq">
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Supybot Frequently Asked Questions</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>18 Feb 2004</date>
|
||||||
|
<revremark>Initial Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.2</revnumber>
|
||||||
|
<date>26 Feb 2004</date>
|
||||||
|
<revremark>Changed to Supybot DTD</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<qandaset defaultlabel="qanda">
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Why does my bot not recognize me or tell me that I don't
|
||||||
|
have the <capability>owner</capability> capability?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Because you've not given it anything to recognize you
|
||||||
|
from! You'll need to identify with the bot
|
||||||
|
(<botcommand>help identify</botcommand> to see how that
|
||||||
|
works) or add your hostmask to your user record
|
||||||
|
(<botcommand>help addhostmask</botcommand> to see how that
|
||||||
|
works) for it to know that you're you. You may wish to
|
||||||
|
note that <botcommand>addhostmask</botcommand> can accept
|
||||||
|
a password; rather than identify, you can send the command
|
||||||
|
<botcommand>addhostmask myOwnerUser [hostmask]
|
||||||
|
myOwnerUserPassword</botcommand> and the bot will add your
|
||||||
|
current hostmask to your owner user (of course, you should
|
||||||
|
change <literal>myOwnerUser</literal> and
|
||||||
|
<literal>myOwnerUserPassword</literal> appropriately for
|
||||||
|
your bot).
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
How do I make Supybot op my users?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
First, you'll have to make sure that your users register
|
||||||
|
with the bot. They can do this with the
|
||||||
|
<botcommand>register</botcommand> command. After they do
|
||||||
|
so, you'll want to add the
|
||||||
|
<capability>#channel,op</capability> capability to their
|
||||||
|
user. Use the <botcommand>channel
|
||||||
|
addcapability</botcommand> command to do this. After
|
||||||
|
that, your users should be able to use the
|
||||||
|
<botcommand>op</botcommand> command to get ops.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If you want your users to be auto-opped when they join the
|
||||||
|
channel, you'll need to load the <plugin>Enforcer</plugin>
|
||||||
|
plugin and turn its <registrygroup>autoOp</registrygroup>
|
||||||
|
configuration variable on. Use the
|
||||||
|
<botcommand>config</botcommand> command to do so. Here's
|
||||||
|
an example of how to do these steps:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch|lambda> I'm going to make an example session for giving
|
||||||
|
you auto-ops, for our FAQ.
|
||||||
|
<dunk1> ah ok ;]
|
||||||
|
<jemfinch|lambda> First, I need you to register with supybot, using
|
||||||
|
the "register" command (remember to send it in private).
|
||||||
|
<dunk1> done
|
||||||
|
<jemfinch|lambda> what name are you registered under?
|
||||||
|
<dunk1> dunk1
|
||||||
|
<jemfinch|lambda> ok, cool.
|
||||||
|
<jemfinch|lambda> @channel addcapability dunk1 op
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> now use the "op" command to get ops.
|
||||||
|
<dunk1> @op
|
||||||
|
— supybot gives channel operator status to dunk1
|
||||||
|
<dunk1> works!
|
||||||
|
<dunk1> ;]
|
||||||
|
<jemfinch|lambda> @load Enforcer
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> @config channel supybot.plugins.Enforcer.autoOp On
|
||||||
|
<supybot> jemfinch|lambda: The operation succeeded.
|
||||||
|
<jemfinch|lambda> ok, now cycle the channel (part and then rejoin)
|
||||||
|
<– dunk1 (dunker@freebsd.nl) has left #supybot
|
||||||
|
–> dunk1 (dunker@freebsd.nl) has joined #supybot
|
||||||
|
— supybot gives channel operator status to dunk1
|
||||||
|
<jemfinch|lambda> cool, thanks :)
|
||||||
|
</ircsession>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Can users with the <capability>admin</capability>
|
||||||
|
capability change configuration variables?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Currently, no. Since this is the first release of Supybot
|
||||||
|
that uses the registry, we wanted to stay on the
|
||||||
|
conservative side and require the
|
||||||
|
<capability>owner</capability> capability for changing all
|
||||||
|
non-channel-related configuration variables. Feel free to
|
||||||
|
make your case to us as to why a certain configuration
|
||||||
|
variable should only require the
|
||||||
|
<capability>admin</capability> capability instead of the
|
||||||
|
<capability>owner</capability> capability, and if we agree
|
||||||
|
with you, we'll change it for the next release.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Can Supybot do factoids?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Supybot most certainly can! In fact, we offer three
|
||||||
|
full-fledged factoids-related plugins!
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<plugin>Factoids</plugin> (written by
|
||||||
|
<nick>jemfinch</nick>) is Supybot's original
|
||||||
|
factoids-related plugin. It offers full integration with
|
||||||
|
Supybot's nested commands as well as a complete 1:n key to
|
||||||
|
factoid ratio, with lookup by individual number. Factoids
|
||||||
|
also uses a channel-specific database instead of a global
|
||||||
|
database though that's configurable with the
|
||||||
|
<registrygroup>supybot.databases.plugins.channelSpecific</registrygroup>
|
||||||
|
configuration variable.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<plugin>MoobotFactoids</plugin> (written by
|
||||||
|
<nick>Strike</nick>) is much more full-featured, offering
|
||||||
|
users the ability to define factoids in a slightly more
|
||||||
|
user-friendly way, as well as parsing factoids to handle
|
||||||
|
<reply>, <action>, and alternations (defining
|
||||||
|
a factoid “test” as
|
||||||
|
“<reply>(foo|bar|baz)” will make the bot
|
||||||
|
send “foo” or “bar” or
|
||||||
|
“baz” to the channel (without the normal
|
||||||
|
“test is ” at the beginning)). If you're
|
||||||
|
accustomed to Moobot's factoids or Blootbot's factoids,
|
||||||
|
then this is the Factoids plugin for you. Unfortunately,
|
||||||
|
due to the more natural definition syntax (required to be
|
||||||
|
comaptible with Moobot) you can't define Factoids with
|
||||||
|
nested commands; you'll have to evaluate the command first
|
||||||
|
and then copy the result into your factoid definition.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<plugin>Infobot</plugin> (written by
|
||||||
|
<nick>jamessan</nick>) is used for Infobot compatibility;
|
||||||
|
if you still want the basic functionality of Infobot, this
|
||||||
|
is the plugin to use.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Can I import my Infobot/Blootbot/Moobot factoids into
|
||||||
|
Supybot?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
As of present, we have no automated way to do so.
|
||||||
|
<nick>Strike</nick> has written a few scripts for
|
||||||
|
importing a Moobot database into MoobotFactoids, however,
|
||||||
|
so you'll want to talk to him about helping you with that.
|
||||||
|
We're certainly happy to help you convert such databases;
|
||||||
|
if you can provide us with such a database exported to a
|
||||||
|
flat file, we can probably do the rest of the work to
|
||||||
|
write a script that imports it into a database for one of
|
||||||
|
our factoids-related plugins.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Do I really have to use separate databases for each
|
||||||
|
channel?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Of course not! We default to separate databases for each
|
||||||
|
channel because, well, that's what <nick>jemfinch</nick>
|
||||||
|
always thought was reasonable. Anyway, if you change the
|
||||||
|
configuration variable
|
||||||
|
<registrygroup>supybot.databases.plugins.channelSpecific</registrygroup>
|
||||||
|
to <literal>False</literal> instead of
|
||||||
|
<literal>True</literal>, for <emphasis>most</emphasis>
|
||||||
|
databases, each channel will share the same database (the
|
||||||
|
exceptions are <plugin>ChannelStats</plugin>,
|
||||||
|
<plugin>Herald</plugin>, <plugin>Seen</plugin>, and
|
||||||
|
<plugin>WordStats</plugin>, which are inherently rather
|
||||||
|
channel-based).
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Karma doesn't seem to work for me.
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
<plugin>Karma</plugin> by default doesn't acknowledge
|
||||||
|
karma updates. If you check the karma of whatever you
|
||||||
|
increased/decreased, you'll note that your increment or
|
||||||
|
decrement still took place. If you'd rather
|
||||||
|
<plugin>Karma</plugin> acknowledge karma updates, change
|
||||||
|
the
|
||||||
|
<registrygroup>supybot.plugins.Karma.response</registrygroup>
|
||||||
|
configuration variable to <literal>On</literal>.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
I added an alias, but it doesn't work!
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Take a look at <botcommand>help <alias you
|
||||||
|
added></botcommand>. If the alias the bot has listed
|
||||||
|
doesn't match what you're giving it, chances re you need
|
||||||
|
to quote your alias in order for the brackets not to be
|
||||||
|
evaluated. For instance, if you're adding an alias to
|
||||||
|
give you a link to your homepage, you need to say:
|
||||||
|
<para>
|
||||||
|
<ircsession>
|
||||||
|
alias add mylink "format concat http://myhost.com/
|
||||||
|
[urlquote $1]"
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
and not:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
alias add mylink format concat http://myhost.com/
|
||||||
|
[urlquote $1]
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
The first version works; the second version will always
|
||||||
|
return the same url.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
Is there a command that can tell me what capability
|
||||||
|
another command requires?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
No, there isn't, and there probably never will be.
|
||||||
|
Commands have the flexibility to check any capabilities
|
||||||
|
they wish to check; while this flexibility is useful, it
|
||||||
|
also makes it hard to guess what capability a certain
|
||||||
|
command requires. We could make a solution that would
|
||||||
|
work in a large majority of cases, but it wouldn't (and
|
||||||
|
couldn't!) be absolutely correct in all circumstances, and
|
||||||
|
since we're anal and we hate doing things halfway, we
|
||||||
|
probably won't ever add this partial solution.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Besides, is the error message so bad? If we did have such
|
||||||
|
a command, many users would call the command, see that
|
||||||
|
they could perform it, and then run the command, thus
|
||||||
|
doubling the activity in the channel. Is that something
|
||||||
|
you want?
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
How do I make my Supybot connect to multiple servers?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Just use the <botcommand>connect</botcommand> command in
|
||||||
|
the <plugin>Owner</plugin> plugin. Easy as pie!
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>
|
||||||
|
I found a bug, what do I do?
|
||||||
|
</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para>
|
||||||
|
Submit it on Sourceforge through our Sourceforge project
|
||||||
|
page:
|
||||||
|
<ulink
|
||||||
|
url="http://sourceforge.net/tracker/?group_id=58965&atid=489447">
|
||||||
|
http://sourceforge.net/tracker/?group_id=58965&atid=489447
|
||||||
|
</ulink>. If Sourceforge happens to be down when you try
|
||||||
|
to submit your bug, then post it in the "Supybot Developer
|
||||||
|
Discussion" forum at our forums at
|
||||||
|
<ulink url="http://forums.supybot.org">
|
||||||
|
http://forums.supybot.org/
|
||||||
|
</ulink>. If that doesn't work, email
|
||||||
|
<email>supybot-bugs@lists.sourceforge.net</email>. If
|
||||||
|
that doesn't work, email
|
||||||
|
<email>jemfinch@supybot.org</email>. If that doesn't
|
||||||
|
work, find yourself some carrier pigeons and … hah!
|
||||||
|
You thought I was serious!
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Anyway, when you submit your bug, we'll need several
|
||||||
|
things. If the bug involved an uncaught exception, we
|
||||||
|
need the traceback (basically the stuff from
|
||||||
|
“Uncaught exception in …” to the next
|
||||||
|
log entry). We'd also like to see the commands that
|
||||||
|
caused the bug, or happened around the time you saw the
|
||||||
|
bug. If the bug involved a database, we'd love to see the
|
||||||
|
database. Remember, it's always worse to send us too
|
||||||
|
little information in a bug report than too much.
|
||||||
|
</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
</qandaset>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
|
||||||
297
docs/DocBook/getting_started.sgml
Normal file
297
docs/DocBook/getting_started.sgml
Normal file
@ -0,0 +1,297 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
|
||||||
|
<article>
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Getting started with Supybot</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>18 Feb 2004</date>
|
||||||
|
<revremark>Initial Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<sect1>
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
Ok, so you've decided to try out Supybot. That's great! The more
|
||||||
|
people who use Supybot, the more people can submit bugs and help
|
||||||
|
us to make it the best IRC bot in the world :)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
First things first: Supybot <emphasis>requires</emphasis> Python
|
||||||
|
2.3. There ain't no getting around it. If you're a Python
|
||||||
|
developer, you probably know how superior 2.3 is to previous
|
||||||
|
incarnations. If you're not, just think about the difference
|
||||||
|
between a bowl of plain vanilla ice cream and a banana split. Or
|
||||||
|
something like that. Either way, <emphasis>we're</emphasis>
|
||||||
|
Python developers and we like banana splits.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Installing the bot and its utilities</title>
|
||||||
|
<para>
|
||||||
|
So what do you do? First thing you'll want to do is run (with
|
||||||
|
root/admin privileges) <application>python setup.py
|
||||||
|
install</application>. This will install Supybot globally. If
|
||||||
|
you need to install locally for whatever reason, see this <ulink
|
||||||
|
url="http://tinyurl.com/2tb37">forum post</ulink> on how to do so.
|
||||||
|
You'll then have several new programs installed where Python
|
||||||
|
scripts are normally installed on your system
|
||||||
|
(<filename>/usr/bin</filename> or
|
||||||
|
<filename>/usr/local/bin</filename> are common on UNIX systems;
|
||||||
|
<filename>C:\Python23\Scripts</filename> is a common place on
|
||||||
|
Windows; and (watch out, this is a long one :))
|
||||||
|
<filename>/System/Library/Frameworks/Python.framework/Versions/2.3/bin</filename>
|
||||||
|
is a common place on MacOS X.). The two that might be of
|
||||||
|
particular interest to you, the new user, are
|
||||||
|
<script>supybot</script> and
|
||||||
|
<script>supybot-wizard</script> The former
|
||||||
|
(<script>supybot</script> is the script to run an actual
|
||||||
|
bot; the latter (<script>supybot-wizard</script> is an
|
||||||
|
in-depth wizard that provides a nice user interface for creating
|
||||||
|
configuration files for your bot. We'd prefer you to the use
|
||||||
|
<script>supybot-wizard</script>, but if you're in a
|
||||||
|
hurry or don't feel like being asked many questions, just run
|
||||||
|
supybot with no arguments and it'll ask you only the questions
|
||||||
|
necessary ")to run a bot.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Firing up the bot for the first time</title>
|
||||||
|
<para>
|
||||||
|
So after running either of those two programs, you've got a nice
|
||||||
|
registry file handy. If you're not satisfied with your answers
|
||||||
|
to any of the questions you were asked, feel free to run the
|
||||||
|
program again until you're satisfied with all your answers. Once
|
||||||
|
you're satisfied, though, run the
|
||||||
|
<script>supybot</script> program with the
|
||||||
|
registry file you created as an argument. This will start the
|
||||||
|
bot; unless you turned off logging to stdout, you'll see some nice
|
||||||
|
log messages describing what the bot is doing at any particular
|
||||||
|
moment; it may pause for a significant amount of time after saying
|
||||||
|
"Connecting to ..." while the server tries to check its ident.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Your first interactions with the bot</title>
|
||||||
|
<para>
|
||||||
|
Ok, so let's assume your bot connected to the server fine and
|
||||||
|
joined the channels you told it to join. For now we'll assume you
|
||||||
|
named your bot <nick>supybot</nick> (you probably didn't,
|
||||||
|
but it'll make it much clearer in the examples that follow to
|
||||||
|
assume that you did). We'll also assume that you told it to join
|
||||||
|
<channel>#channel</channel> (a nice generic name for a channel,
|
||||||
|
isn't it? :)) So what do you do with this bot that you just made
|
||||||
|
to join your channel? Try this in the channel:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
supybot: list
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Replacing <nick>supybot</nick> with the actual name you
|
||||||
|
picked for your bot, of course. Your bot should reply with a list
|
||||||
|
of the plugins he currently has loaded. At least
|
||||||
|
<plugin>Admin</plugin>, <plugin>Channel</plugin>,
|
||||||
|
<plugin>Config</plugin>, <plugin>Misc</plugin>,
|
||||||
|
<plugin>Owner</plugin>, and <plugin>User</plugin> should be
|
||||||
|
there; if you used <script>supybot-wizard</script> to
|
||||||
|
create your configuration file you may have many more plugins
|
||||||
|
loaded. The <botcommand>list</botcommand> command can also be used to
|
||||||
|
list the commands in a given plugin:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
supybot: list Misc
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Will list all the commands in the <plugin>Misc</plugin> plugin.
|
||||||
|
</para>
|
||||||
|
<sect2>
|
||||||
|
<title>Accessing the bot's online help</title>
|
||||||
|
<para>
|
||||||
|
If you want to see the help for any command, just use
|
||||||
|
the <botcommand>help</botcommand> command:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
supybot: help help
|
||||||
|
supybot: help list
|
||||||
|
supybot: help load
|
||||||
|
</ircsession>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Dealing with ambiguous commands</title>
|
||||||
|
<para>
|
||||||
|
Sometimes more than one plugin will have a given command; for
|
||||||
|
instance, the <botcommand>list</botcommand> command exists in both
|
||||||
|
the <plugin>Misc</plugin> and <plugin>Config</plugin>
|
||||||
|
plugins (both loaded by default). <plugin>List</plugin>, in
|
||||||
|
this case, defaults to the <plugin>Misc</plugin> plugin, but
|
||||||
|
you may want to get the help for the
|
||||||
|
<botcommand>list</botcommand>
|
||||||
|
command in the <plugin>Config</plugin> plugin. In that
|
||||||
|
case, you'll want to give your command like this:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
supybot: help config list
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Anytime your bot tells you that a given command is defined in
|
||||||
|
several plugins, you'll want to use this syntax
|
||||||
|
(<botcommand>plugin command</botcommand>) to disambiguate which
|
||||||
|
plugin's command you wish to call. For instance, if you
|
||||||
|
wanted to call the <plugin>Config</plugin> plugin's
|
||||||
|
<botcommand>list</botcommand> command, then you'd need to say:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
supybot: config list
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Rather than just <botcommand>list</botcommand>.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Loading plugins</title>
|
||||||
|
<para>
|
||||||
|
Now that you know how to deal with plugins having commands
|
||||||
|
with the same name, let's take a look at loading other
|
||||||
|
plugins. If you didn't use
|
||||||
|
<script>supybot-wizard</script>, though, you might
|
||||||
|
do well to try it before playing around with loading plugins
|
||||||
|
yourself: each plugin has its own
|
||||||
|
<function>configure</function> function that the wizard uses
|
||||||
|
to setup the appropriate registry entries if the plugin
|
||||||
|
requires any.
|
||||||
|
</para>
|
||||||
|
<sect3>
|
||||||
|
<title>Identifying yourself as the bot owner</title>
|
||||||
|
<para>
|
||||||
|
Now, if you do want to play around with loading plugins,
|
||||||
|
you're going to need to have the
|
||||||
|
<capability>owner</capability>
|
||||||
|
capability. If you ran the wizard, then chances are you
|
||||||
|
already added an owner user for yourself. If not,
|
||||||
|
however, you can add one via the handy-dandy
|
||||||
|
<script>supybot-adduser</script> script. You'll
|
||||||
|
want to run it while the bot is not running (otherwise it
|
||||||
|
could overwrite
|
||||||
|
<script>supybot-adduser</script>'s changes to
|
||||||
|
your user database before you get a chance to reload
|
||||||
|
them). Just follow the prompts, and when it asks if you
|
||||||
|
want to give the user any capabilities, say yes and then
|
||||||
|
give yourself the <capability>owner</capability> capability
|
||||||
|
(without the quotes), restart the bot and you'll be ready
|
||||||
|
to load some plugins!
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Now, in order for the bot to recognize you as your owner
|
||||||
|
user, you'll have to identify with the bot. Open up a
|
||||||
|
query window in your irc client (/query should do it; if
|
||||||
|
not, just know that you can't identify in a channel
|
||||||
|
because it requires sending your password to the bot).
|
||||||
|
Then type this:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
help identify
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
And follow the instructions; the command you send will
|
||||||
|
probably look like this, with your owner user and password
|
||||||
|
replaced:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
identify myowneruser myuserpassword
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
The bot will tell you that “The operation
|
||||||
|
succeeded” if you got the right name and password.
|
||||||
|
Now that you're identified, you can do anything that
|
||||||
|
requires any privilege: that includes all the commands in
|
||||||
|
the <plugin>Owner</plugin> and <plugin>Admin</plugin>
|
||||||
|
plugins, which you may want to take a look at (using the
|
||||||
|
<botcommand>list</botcommand> and
|
||||||
|
<botcommand>help</botcommand>
|
||||||
|
commands, of course). One command in particular that you
|
||||||
|
might want to use (it's from the <plugin>User</plugin>
|
||||||
|
plugin) is the <botcommand>addhostmask</botcommand> command: it
|
||||||
|
lets you add a hostmask to your user record so the bot
|
||||||
|
recognizes you by your hostmask instead of requiring you
|
||||||
|
to always identify with it before it recognizes you. Use
|
||||||
|
the <botcommand>help</botcommand> command to see how this
|
||||||
|
command works. Here's how I often use it:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
addhostmask myuser [hostmask] mypassword
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
You may not have seen that "[hostmask]" syntax before.
|
||||||
|
Supybot allows nested commands, which means that any
|
||||||
|
command's output can be nested as an argument to another
|
||||||
|
command. The hostmask command from the
|
||||||
|
<plugin>Misc</plugin> plugin returns the hostmask of a
|
||||||
|
given nick, but if given no arguments, it returns the
|
||||||
|
hostmask of the person giving the command. So the command
|
||||||
|
above adds the hostmask I'm currently using to my user's
|
||||||
|
list of recognized hostmasks. I'm only required to give
|
||||||
|
<literal>mypassword</literal> if I'm not already
|
||||||
|
identified with the bot.
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>The <botcommand>more</botcommand> command</title>
|
||||||
|
<para>
|
||||||
|
Another command you might find yourself needing somewhat often
|
||||||
|
is the <botcommand>more</botcommand> command. The IRC protocol
|
||||||
|
limits messages to 512 bytes, 60 or so of which must be
|
||||||
|
devoted to some bookkeeping. Sometimes, however, Supybot
|
||||||
|
wants to send a message that's longer than that. What it
|
||||||
|
does, then, is break it into "chunks" and send the first one,
|
||||||
|
following it with "(X more messages)" where X is how many more
|
||||||
|
chunks there are. To get to these chunks, use the more
|
||||||
|
command. One way to try is to look at the listing of
|
||||||
|
configuration groups for the bot (more on this in the
|
||||||
|
CONFIGURATION document) by giving the command "config list
|
||||||
|
supybot". Last I checked, it'll overflow into a second chunk.
|
||||||
|
When you invoke this command, you should see output like:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<supybot> nick, ident, user, server, password, channels, prefixChars,
|
||||||
|
defaultCapabilities, defaultAllow, defaultIgnore,
|
||||||
|
humanTimestampFormat, externalIP, bracketSyntax, pipeSyntax,
|
||||||
|
followIdentificationThroughNickChanges, alwaysJoinOnInvite,
|
||||||
|
showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
|
||||||
|
snarfThrottle, threadAllCommands, pingServer, pingInterval,
|
||||||
|
upkeepInterval, flush, (1 more message)
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Now, to see the rest of the output, simply give the command
|
||||||
|
<botcommand>more</botcommand>, and it will show you the rest:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch> more
|
||||||
|
<supybot> httpPeekSize, and defaultSocketTimeout
|
||||||
|
</ircsession>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>You're ready!</title>
|
||||||
|
<para>
|
||||||
|
You should now have a solid foundation for using Supybot. Be sure
|
||||||
|
to check the help that is built-in to the bot itself if you have
|
||||||
|
any questions, and enjoy using Supybot!
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
|
||||||
585
docs/DocBook/interfaces.sgml
Normal file
585
docs/DocBook/interfaces.sgml
Normal file
@ -0,0 +1,585 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
|
||||||
|
<article>
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Supybot developer interfaces</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>19 Feb 2004</date>
|
||||||
|
<revremark>Initial Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.2</revnumber>
|
||||||
|
<date>26 Feb 2004</date>
|
||||||
|
<revremark>Converted to Supybot DTD</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<sect1>
|
||||||
|
<title>Available interfaces</title>
|
||||||
|
<para>
|
||||||
|
These are the interfaces for some of the objects you'll deal with
|
||||||
|
if you code for Supybot.
|
||||||
|
</para>
|
||||||
|
<sect2>
|
||||||
|
<title><classname>ircmsgs.IrcMsg</classname>
|
||||||
|
<para>
|
||||||
|
This is the object that represents an IRC message. It has
|
||||||
|
several methods and attributes. The most important thing
|
||||||
|
about this class, however, is that it <emphasis>is</emphasis>
|
||||||
|
hashable, and thus <emphasis>cannot</emphasis> be modified.
|
||||||
|
Do not change any attributes; any code that modifies an IRC
|
||||||
|
message is <emphasis>broken</emphasis> and should not exist.
|
||||||
|
</para>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting methods</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>__init__</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
One of the more complex initializers in a class.
|
||||||
|
It can be used in three different ways:
|
||||||
|
</para>
|
||||||
|
<orderedlist numeration="arabic" spacing="normal">
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
It can be given a string, as one received
|
||||||
|
from the server, which it will then parse
|
||||||
|
into its separate components and
|
||||||
|
instantiate the class with those
|
||||||
|
components as attributes.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
It can be given a command, some (optional)
|
||||||
|
arguments, and a (optional) prefix, and
|
||||||
|
will instantiate the class with those
|
||||||
|
components as attributes.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
It can be given, in addition to any of the
|
||||||
|
above arguments, a <varname>msg</varname>
|
||||||
|
keyword argument that will use the
|
||||||
|
attributes of msg as defaults. This
|
||||||
|
exists to make it easier to copy messages,
|
||||||
|
since the class is immutable.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>__str__</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
This returns the message in a string form suitable
|
||||||
|
for sending to a server.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>__repr__</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
This returns the message in a form suitable for
|
||||||
|
<function>eval()</function>, assuming the name
|
||||||
|
<varname>IrcMsg</varname> is in your namespace and
|
||||||
|
is bound to this class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
<para>
|
||||||
|
The following attributes are the meat of this class. These
|
||||||
|
are generally what you'll be looking at with
|
||||||
|
<varname>IrcMsg</varname>s.
|
||||||
|
</para>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting attributes</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>command</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
This is the command of the
|
||||||
|
<varname>IrcMsg</varname> –
|
||||||
|
<literal>PRIVMSG</literal>,
|
||||||
|
<literal>NOTICE</literal>,
|
||||||
|
<literal>WHOIS</literal>,
|
||||||
|
etc.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>args</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
This is a tuple of the arguments to the
|
||||||
|
<varname>IrcMsg</varname>. Some messages have
|
||||||
|
arguments, some don't, depending on what command
|
||||||
|
they are. You are, of course, always assured that
|
||||||
|
<varname>args</varname> exists and is a tuple,
|
||||||
|
though it might be empty.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>prefix</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
This is the hostmask of the person/server the
|
||||||
|
message is from. In general, you won't be setting
|
||||||
|
this on your outgoing messages, but incoming
|
||||||
|
messages will always have one. This is the whole
|
||||||
|
hostmask; if the message was received from a
|
||||||
|
server, it'll be the server's hostmask; if the
|
||||||
|
message was received from a user, it'll be the
|
||||||
|
whole user hostmask. In that case, however, it's
|
||||||
|
also parsed out into the
|
||||||
|
<varname>nick</varname>/<varname>user</varname>/<varname>host</varname>
|
||||||
|
attributes, which are probably more useful to
|
||||||
|
check for many purposes.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>nick</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If the message was sent by a user, this will be
|
||||||
|
the nick of the user. If it was sent by a server,
|
||||||
|
this will be the server's name (something like
|
||||||
|
<literal>calvino.freenode.net</literal> or
|
||||||
|
similar).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>user</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If the message was sent by a user, this will be
|
||||||
|
the user string of the user – what they put
|
||||||
|
into their IRC client for their "full name." If
|
||||||
|
it was sent by a server, it'll be the server's
|
||||||
|
name, again.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>host</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If the message was sent by a user, this will be
|
||||||
|
the host portion of their hostmask. If it was
|
||||||
|
sent by a server, it'll be the server's name (yet
|
||||||
|
again :))
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title><classname>irclib.Irc</classname>
|
||||||
|
<para>
|
||||||
|
This is the object to handle everything about IRC except the
|
||||||
|
actual connection to the server itself.
|
||||||
|
(<emphasis>NOTE</emphasis> that the object actually received
|
||||||
|
by commands in subclasses of
|
||||||
|
<classname>callbacks.Privmsg</classname> is an
|
||||||
|
<classname>IrcObjectProxy</classname>, which is described
|
||||||
|
later. It augments the following interface with several
|
||||||
|
methods of its own to help plugin authors.)
|
||||||
|
</para>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting methods</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>queueMsg</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Queues a message for sending to the server. The
|
||||||
|
queue is generally FIFO, but it does prioritize
|
||||||
|
messages based on their command.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>sendMsg</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Queues a message for sending to the server prior
|
||||||
|
to any messages in the normal queue. This is
|
||||||
|
exactly a FIFO queue, no reordering is done at
|
||||||
|
all.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<!--<note>
|
||||||
|
<para>
|
||||||
|
The following two methods are the most important for
|
||||||
|
people writing new <varname>IrcDriver</varname>s.
|
||||||
|
Otherwise, you really don't need to pay attention to
|
||||||
|
them.
|
||||||
|
</para>
|
||||||
|
</note>-->
|
||||||
|
<varlistentry>
|
||||||
|
<term>feedMsg</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Feeds the <varname>Irc</varname> object a message
|
||||||
|
for it handle appropriately, as well as passing it
|
||||||
|
on to callbacks.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>takeMsg</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If the <varname>Irc</varname> object has a message
|
||||||
|
it's ready to send to the server, this will return
|
||||||
|
it. Otherwise, it will return
|
||||||
|
<literal>None</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<!--<note>
|
||||||
|
<para>
|
||||||
|
The next several methods are of far more marginal
|
||||||
|
utility. But someone may need them, so they're
|
||||||
|
documented here.
|
||||||
|
</para>
|
||||||
|
</note>-->
|
||||||
|
<varlistentry>
|
||||||
|
<term>addCallback</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Takes a callback to add to the list of callbacks
|
||||||
|
in the <varname>Irc</varname> object. See the
|
||||||
|
interface for <varname>IrcCallback</varname> for
|
||||||
|
more information.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>getCallback</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Gets a callback by name, if it is in the
|
||||||
|
<varname>Irc</varname> object's list of callbacks.
|
||||||
|
If it it isn't, returns <literal>None</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>removeCallback</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Removes a callback by name. Returns a list of the
|
||||||
|
callbacks removed (since it is technically
|
||||||
|
possible to have multiple callbacks with the same
|
||||||
|
name. This list may be empty.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>__init__</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Requires a <varname>nick</varname>. Optional
|
||||||
|
arguments include <varname>user</varname> and
|
||||||
|
<varname>ident</varname>, which default to the
|
||||||
|
nick given, <varname>password</varname>, which
|
||||||
|
defaults to the empty password, and
|
||||||
|
<varname>callbacks</varname>, a list of callbacks
|
||||||
|
(which defaults to nothing, an empty list).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>reset</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Resets the <varname>Irc</varname> object to its
|
||||||
|
original state, as well as sends a
|
||||||
|
<function>reset()</function> to every callbacks.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>die</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Kills the IRC object and all its callbacks.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting attributes</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>nick</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The current nick of the bot.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>prefix</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The current prefix of the bot.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>server</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The current server the bot is connected to.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>network</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The current network name the bot is connected to.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>afterConnect</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<literal>False</literal> until the bot has
|
||||||
|
received a command sent after the connection is
|
||||||
|
finished – 376, 377, or 422.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>state</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
An <varname>IrcState</varname> object for this
|
||||||
|
particular connection. See the interface for the
|
||||||
|
<varname>IrcState</varname> object for more
|
||||||
|
information.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title><classname>irclib.IrcCallback</classname></title>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting Methods</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>name</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Returns the name of the callback. The default
|
||||||
|
implementation simply returns the name of the
|
||||||
|
class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>__call__</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called by the <varname>Irc</varname> object with
|
||||||
|
itself and the message whenever a message is fed
|
||||||
|
to the <varname>Irc</varname> object. Nothing is
|
||||||
|
done with the return value.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>inFilter</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called by the <varname>Irc</varname> object with
|
||||||
|
itself and the message whenever a message is fed
|
||||||
|
to the <varname>Irc</varname> object. The return
|
||||||
|
value should be an <varname>IrcMsg</varname>
|
||||||
|
object to be passed to the next callback in the
|
||||||
|
<varname>Irc</varname>'s list of callbacks. If
|
||||||
|
<literal>None</literal> is returned, all
|
||||||
|
processing stops. This gives callbacks an
|
||||||
|
oppurtunity to "filter" incoming messages before
|
||||||
|
general callbacks are given them.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>outFilter</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Basically equivalent to
|
||||||
|
<varname>inFilter</varname>, except instead of
|
||||||
|
being called on messages as they enter the
|
||||||
|
<varname>Irc</varname> object, it's called on
|
||||||
|
messages as they leave the <varname>Irc</varname>
|
||||||
|
object.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>die</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called when the parent <varname>Irc</varname> is
|
||||||
|
told to die. This gives callbacks an oppurtunity
|
||||||
|
to close open files, network connections, or
|
||||||
|
databases before they're deleted.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>reset</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called when the parent <varname>Irc</varname> is
|
||||||
|
told to reset (which is generally when
|
||||||
|
reconnecting to the server). Most callbacks don't
|
||||||
|
need to define this.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting attributes</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>priority</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Determines the priority of the callback in the
|
||||||
|
<varname>Irc</varname> object's list of callbacks.
|
||||||
|
Defaults to <literal>99</literal>; the valid range
|
||||||
|
includes <literal>0</literal> through
|
||||||
|
<literal>sys.maxint-1</literal> (don't use
|
||||||
|
<literal>sys.maxint</literal> itself, that's
|
||||||
|
reserved for the <varname>Misc</varname> plugin).
|
||||||
|
The lower the number, the higher the priority.
|
||||||
|
High priority callbacks are called earlier in the
|
||||||
|
<varname>inFilter</varname> cycle, earlier in the
|
||||||
|
<varname>__call__</varname> cycle, and later in
|
||||||
|
the <varname>outFilter</varname> cycle –
|
||||||
|
basically, they're given the first chances on the
|
||||||
|
way in and the last chances on the way out.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title><classname>callbacks.IrcObjectProxy</classname></title>
|
||||||
|
<para>
|
||||||
|
<classname>IrcObjectProxy</classname> is a proxy for an
|
||||||
|
<classname>irclib.Irc</classname> instance that serves to
|
||||||
|
provide a much fuller interface for handling replies and
|
||||||
|
errors as well as to handle the nesting of commands. This is
|
||||||
|
what you'll be dealing with almost all the time when writing
|
||||||
|
commands; when writing <function>doCommand</function> methods
|
||||||
|
(the kind you read about in the interface description of
|
||||||
|
<classname>irclib.IrcCallback</classname>) you'll be dealing
|
||||||
|
with plain old <classname>irclib.Irc</classname> objects.
|
||||||
|
</para>
|
||||||
|
<variablelist>
|
||||||
|
<title>Interesting methods</title>
|
||||||
|
<varlistentry>
|
||||||
|
<term>reply</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called to reply to the current message with a
|
||||||
|
string that is to be the reply. Uses the
|
||||||
|
<function>queueMsg</function> command discussed in
|
||||||
|
the <classname>irclib.Irc</classname> section.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>replySuccess</term>
|
||||||
|
<term>replyError</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
These reply with the configured responses for
|
||||||
|
success and generic error, respectively. If an
|
||||||
|
additional argument is given, it's (intelligently)
|
||||||
|
appended to the generic message to be more
|
||||||
|
specific.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>error</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Called to send an error reply to the current
|
||||||
|
message; not only does the response indicate an
|
||||||
|
error, but commands that error out break the
|
||||||
|
nested-command chain, which is generally useful
|
||||||
|
for not confusing the user :)
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>errorNoCapability</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Like <function>error</function>, except it accepts
|
||||||
|
the capability that's missing and integrates it
|
||||||
|
into the configured error message for such things.
|
||||||
|
Also accepts an additional string for a more
|
||||||
|
descriptive message, if that's what you want.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>errorPossibleBug</term>
|
||||||
|
<term>errorNotRegistered</term>
|
||||||
|
<term>errorNoUser</term>
|
||||||
|
<term>errorRequiresPrivacy</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
These methods reply with the appropriate
|
||||||
|
configured error message for the conditions in
|
||||||
|
their names; they all take an additional arguments
|
||||||
|
to be more specific about the conditions they
|
||||||
|
indicate, but this argument is very rarely
|
||||||
|
necessary.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>getRealIrc</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Returns the actual <classname>Irc</classname>
|
||||||
|
object being proxied for.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
|
||||||
633
docs/DocBook/plugin-example.sgml
Normal file
633
docs/DocBook/plugin-example.sgml
Normal file
@ -0,0 +1,633 @@
|
|||||||
|
<!DOCTYPE article SYSTEM "supybot.dtd">
|
||||||
|
|
||||||
|
<article>
|
||||||
|
<articleinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jeremiah</firstname>
|
||||||
|
<surname>Fincher</surname>
|
||||||
|
</author>
|
||||||
|
<editor>
|
||||||
|
<firstname>Daniel</firstname>
|
||||||
|
<surname>DiPaolo</surname>
|
||||||
|
<contrib>DocBook translator</contrib>
|
||||||
|
</editor>
|
||||||
|
</authorgroup>
|
||||||
|
<title>Supybot plugin author example</title>
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.1</revnumber>
|
||||||
|
<date>13 Sep 2003</date>
|
||||||
|
<revremark>Initial revision</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.2</revnumber>
|
||||||
|
<date>14 Sep 2003</date>
|
||||||
|
<revremark>Converted to DocBook</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.3</revnumber>
|
||||||
|
<date>24 Nov 2003</date>
|
||||||
|
<revremark>
|
||||||
|
Updated to match EXAMPLE included with 0.75.0
|
||||||
|
</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.4</revnumber>
|
||||||
|
<date>26 Feb 2004</date>
|
||||||
|
<revremark>Converted to use Supybot DTD</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>0.5</revnumber>
|
||||||
|
<date>4 Sep 2004</date>
|
||||||
|
<revremark>Updated Docbook translation</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</articleinfo>
|
||||||
|
<sect1>
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
Ok, so you want to write a callback for supybot. Good, then this
|
||||||
|
is the place to be. We're going to start from the top (the
|
||||||
|
highest level, where supybot code does the most work for you) and
|
||||||
|
move lower after that.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So have you used supybot? If not, you need to go use it, get a
|
||||||
|
feel for it, see how the various commands work and such.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So now that we know you've used supybot, we'll start getting into
|
||||||
|
details.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Creating your own plugin</title>
|
||||||
|
<sect2>
|
||||||
|
<title>
|
||||||
|
Using <script>scripts/newplugin.py</script>
|
||||||
|
</title>
|
||||||
|
<para>
|
||||||
|
First, the easiest way to start writing a module is to use the
|
||||||
|
wizard provided, <script>scripts/newplugin.py</script>.
|
||||||
|
Here's an example session:
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
functor% scripts/newplugin.py
|
||||||
|
What should the name of the plugin be? Random
|
||||||
|
Supybot offers two major types of plugins: command-based and regexp-
|
||||||
|
based. Command-based plugins are the kind of plugins you've seen most
|
||||||
|
when you've used supybot. They're also the most featureful and
|
||||||
|
easiest to write. Commands can be nested, for instance, whereas
|
||||||
|
regexp-based callbacks can't do nesting. That doesn't mean that
|
||||||
|
you'll never want regexp-based callbacks. They offer a flexibility
|
||||||
|
that command-based callbacks don't offer; however, they don't tie into
|
||||||
|
the whole system as well. If you need to combine a command-based
|
||||||
|
callback with some regexp-based methods, you can do so by subclassing
|
||||||
|
callbacks.PrivmsgCommandAndRegexp and then adding a class-level
|
||||||
|
attribute "regexps" that is a sets.Set of methods that are regexp-
|
||||||
|
based. But you'll have to do that yourself after this wizard is
|
||||||
|
finished :)
|
||||||
|
Do you want a command-based plugin or a regexp-based plugin? [command/
|
||||||
|
regexp] command
|
||||||
|
Sometimes you'll want a callback to be threaded. If its methods
|
||||||
|
(command or regexp-based, either one) will take a signficant amount
|
||||||
|
of time to run, you'll want to thread them so they don't block
|
||||||
|
the entire bot.
|
||||||
|
|
||||||
|
Does your plugin need to be threaded? [y/n] n
|
||||||
|
Your new plugin template is in plugins/Random.py
|
||||||
|
functor%
|
||||||
|
</screen>
|
||||||
|
<para>
|
||||||
|
So that's what it looks like. Now let's look at the source
|
||||||
|
code (if you'd like to look at it in your programming editor,
|
||||||
|
the whole plugin is available as
|
||||||
|
<filename>examples/Random.py</filename>):
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
#!/usr/bin/env python
|
||||||
|
|
||||||
|
###
|
||||||
|
# Copyright (c) 2004, Jeremiah Fincher
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
#
|
||||||
|
# * Redistributions of source code must retain the above copyright notice,
|
||||||
|
# this list of conditions, and the following disclaimer.
|
||||||
|
# * Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions, and the following disclaimer in the
|
||||||
|
# documentation and/or other materials provided with the distribution.
|
||||||
|
# * Neither the name of the author of this software nor the name of
|
||||||
|
# contributors to this software may be used to endorse or promote products
|
||||||
|
# derived from this software without specific prior written consent.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
||||||
|
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||||
|
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||||
|
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||||
|
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||||
|
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||||
|
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||||
|
# POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
###
|
||||||
|
|
||||||
|
"""
|
||||||
|
Add the module docstring here. This will be used by the setup.py script.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__revision__ = "$Id$"
|
||||||
|
__author__ = ''
|
||||||
|
|
||||||
|
import supybot.plugins as plugins
|
||||||
|
|
||||||
|
import supybot.conf as conf
|
||||||
|
import supybot.utils as utils
|
||||||
|
import supybot.privmsgs as privmsgs
|
||||||
|
import supybot.callbacks as callbacks
|
||||||
|
|
||||||
|
|
||||||
|
def configure(onStart, afterConnect, advanced):
|
||||||
|
# This will be called by setup.py to configure this module. Advanced is
|
||||||
|
# a bool that specifies whether the user identified himself as an advanced
|
||||||
|
# user or not. You should effect your configuration by manipulating the
|
||||||
|
# registry as appropriate.
|
||||||
|
from questions import expect, anything, something, yn
|
||||||
|
conf.registerPlugin('Random', True)
|
||||||
|
|
||||||
|
class Random(callbacks.Privmsg):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
Class = Random
|
||||||
|
|
||||||
|
# vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78:
|
||||||
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Customizing the boilerplate code</title>
|
||||||
|
<para>
|
||||||
|
So a few notes, before we customize it.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You'll probably want to change the copyright notice to be your
|
||||||
|
name. It wouldn't stick even if you kept my name, so you
|
||||||
|
might as well :)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Describe what you want the plugin to do in the docstring.
|
||||||
|
This is used in <script>scripts/setup.py</script> in
|
||||||
|
order to explain to the user the purpose of the module. It's
|
||||||
|
also returned when someone asks the bot for help for a given
|
||||||
|
module (instead of help for a certain command). We'll change
|
||||||
|
this one to <literal>"Lots of stuff relating to random
|
||||||
|
numbers."</literal>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Then there are the imports. The
|
||||||
|
<module>callbacks</module>
|
||||||
|
module is used (the class you're given subclasses
|
||||||
|
<classname>callbacks.Privmsg</classname>) but the
|
||||||
|
<module>privmsgs</module> module isn't used. That's
|
||||||
|
alright; we can almost guarantee you'll use it, so we go ahead
|
||||||
|
and add the import to the template.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Then you see a <function>configure</function> function. This
|
||||||
|
the function that's called when users decide to add your
|
||||||
|
module in <script>scripts/setup.py</script>. You'll
|
||||||
|
note that by default it simply registers the plugin to be
|
||||||
|
automatically loaded on startup. For many
|
||||||
|
plugins this is all you need; for more complex plugins, you
|
||||||
|
might need to ask questions and add commands based on the
|
||||||
|
answers.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Digging in: customizing the plugin class</title>
|
||||||
|
<para>
|
||||||
|
Now comes the meat of the plugin: the plugin class.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
What you're given is a skeleton: a simple subclass of
|
||||||
|
<classname>callbacks.Privmsg</classname> for you to start
|
||||||
|
with. Now let's add a command.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
I don't know what you know about random number generators, but
|
||||||
|
the short of it is that they start at a certain number (a
|
||||||
|
seed) and they continue (via some somewhat
|
||||||
|
complicated/unpredictable algorithm) from there. This seed
|
||||||
|
(and the rest of the sequence, really) is all nice and
|
||||||
|
packaged up in Python's <module>random</module> module, the
|
||||||
|
<varname>Random</varname> object. So the first thing we're
|
||||||
|
going to have to do is give our plugin a
|
||||||
|
<varname>Random</varname> object.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Normally, when we want to give instances of a class an object,
|
||||||
|
we'll do so in the <function>__init__</function> method. And
|
||||||
|
that works great for plugins, too. The one thing you have to
|
||||||
|
be careful of is that you call the superclass
|
||||||
|
<function>__init__</function> method at the end of your own
|
||||||
|
<function>__init__</function>. So to add this
|
||||||
|
<classname>random.Random</classname> object to our plugin, we
|
||||||
|
can replace the <keyword>pass</keyword> statement with
|
||||||
|
this:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def __init__(self):
|
||||||
|
self.rng = random.Random()
|
||||||
|
callbacks.Privmsg.__init__(self)
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
(<varname>rng</varname>is an abbreviation for "random number
|
||||||
|
generator," in case you were curious)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Do be careful not to give your <function>__init__</function>
|
||||||
|
any arguments (other than <varname>self</varname>, of course).
|
||||||
|
There's no way anything will ever get to them! If you have
|
||||||
|
some sort of initial values you need to get to your plugin
|
||||||
|
before it can do anything interesting, you should get those
|
||||||
|
values from the registry.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
There's an easier way to get our plugin to have its own rng
|
||||||
|
than to define an <function>__init__</function>. Plugins are
|
||||||
|
unique among classes because we're always certain that there
|
||||||
|
will only be one instance -- supybot doesn't allow us to load
|
||||||
|
multiple instances of a single plugin. So instead of adding
|
||||||
|
the rng in <function>__init__</function>, we can just add it
|
||||||
|
as a attribute to the class itself. Like so (replacing the
|
||||||
|
<function>pass</function> statement again):
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
rng = random.Random()
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
And we save two lines of code and make our code a little more
|
||||||
|
clear :)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Now that we have an RNG, we need some way to get random
|
||||||
|
numbers. So first, we'll add a command that simply gets the
|
||||||
|
next random number and gives it back to the user. It takes no
|
||||||
|
arguments, of course (what would you give it?). Here's the
|
||||||
|
command, and I'll follow that with the explanation of what
|
||||||
|
each part means.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def random(self, irc, msg, args):
|
||||||
|
"""takes no arguments
|
||||||
|
|
||||||
|
Returns the next random number generated by the random number
|
||||||
|
generator.
|
||||||
|
"""
|
||||||
|
irc.reply(str(self.rng.random()))
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
And that's it! Pretty simple, huh? Anyway, you're probably
|
||||||
|
wondering what all that <emphasis>means</emphasis>. We'll
|
||||||
|
start with the <keyword>def</keyword> statement:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def random(self, irc, msg, args):
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
What that does is define a command
|
||||||
|
<botcommand>random</botcommand>. You can call it by saying
|
||||||
|
"@random" (or whatever prefix character your specific bot
|
||||||
|
uses). The arguments are a bit less obvious.
|
||||||
|
<varname>self</varname> is self-evident (hah!).
|
||||||
|
<varname>irc</varname> is the <classname>Irc</classname>
|
||||||
|
object passed to the command; <varname>msg</varname> is the
|
||||||
|
original <classname>IrcMsg</classname> object. But you're
|
||||||
|
really not going to have to deal with either of these too much
|
||||||
|
(with the exception of calling <function>irc.reply</function>
|
||||||
|
or <function>irc.error</function>). What you're
|
||||||
|
<emphasis>really</emphasis> interested in is the
|
||||||
|
<varname>args</varname> arg. That is a list of all the
|
||||||
|
arguments passed to your command, pre-parsed and already
|
||||||
|
evaluated (i.e., you never have to worry about nested
|
||||||
|
commands, or handling double quoted strings, or splitting on
|
||||||
|
whitespace – the work has already been done for you).
|
||||||
|
You can read about the <classname>Irc</classname> object in
|
||||||
|
<filename>irclib.py</filename> (you won't find
|
||||||
|
<function>.reply</function> or <function>.error</function>
|
||||||
|
there, though, because you're actually getting an
|
||||||
|
<classname>IrcObjectProxy</classname>, but that's beyond the
|
||||||
|
level we want to describe here :)). You can read about the
|
||||||
|
<varname>msg</varname> object in
|
||||||
|
<filename>ircmsgs.py</filename>. But again, you'll very
|
||||||
|
rarely be using these objects.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
(In case you're curious, the answer is yes, you
|
||||||
|
<emphasis>must</emphasis> name your arguments <varname>(self,
|
||||||
|
irc, msg, args)</varname>. The names of those arguments is
|
||||||
|
one of the ways that supybot uses to determine which methods
|
||||||
|
in a plugin class are commands and which aren't. And while
|
||||||
|
we're talking about naming restrictions, all your commands
|
||||||
|
should be named in all-lowercase with no underscores. Before
|
||||||
|
calling a command, supybot always converts the command name to
|
||||||
|
lowercase and removes all dashes and underscores. On the
|
||||||
|
other hand, you now know an easy way to make sure a method is
|
||||||
|
never called (even if its arguments are <varname>(self, irc,
|
||||||
|
msg, args)</varname>, however unlikely that may be). Just
|
||||||
|
name it with an underscore or an uppercase letter in it :))
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You'll also note that the docstring is odd. The wonderful
|
||||||
|
thing about the supybot framework is that it's easy to write
|
||||||
|
complete commands with help and everything: the docstring
|
||||||
|
<emphasis>is</emphasis> the help! Given the above docstring,
|
||||||
|
this is what a supybot does:
|
||||||
|
</para>
|
||||||
|
<ircsession>
|
||||||
|
<jemfinch> @help random
|
||||||
|
<angryman> jemfinch: (random takes no arguments) -- Returns the
|
||||||
|
next random number from the random number generator.
|
||||||
|
</ircsession>
|
||||||
|
<para>
|
||||||
|
Now on to the actual body of the function:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
irc.reply(msg, str(self.rng.random()))
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
<function>irc.reply</function> simply takes one simple
|
||||||
|
argument: a string The string is the reply to be sent. Don't
|
||||||
|
worry about length restrictions or anything
|
||||||
|
– if the string you want to send is too big for an IRC
|
||||||
|
message (and oftentimes that turns out to be the case :)) the
|
||||||
|
Supybot framework handles that entirely transparently to you.
|
||||||
|
Do make sure, however, that you give
|
||||||
|
<function>irc.reply</function> a string. It doesn't take
|
||||||
|
anything else (sometimes even unicode fails!). That's why we
|
||||||
|
have "str(self.rng.random())" instead of simply
|
||||||
|
"self.rng.random()" – we had to give
|
||||||
|
<function>irc.reply</function> a string.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Anyway, now that we have an RNG, we have a need for seed! Of
|
||||||
|
course, Python gives us a good seed already (it uses the
|
||||||
|
current time as a seed if we don't give it one) but users
|
||||||
|
might want to be able to repeat "random" sequences, so letting
|
||||||
|
them set the seed is a good thing. So we'll add a seed
|
||||||
|
command to give the RNG a specific seed:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def seed(self, irc, msg, args):
|
||||||
|
"""<seed>
|
||||||
|
|
||||||
|
Sets the seed of the random number generator. <seed> must be
|
||||||
|
an int or a long.
|
||||||
|
"""
|
||||||
|
seed = privmsgs.getArgs(args)
|
||||||
|
try:
|
||||||
|
seed = long(seed)
|
||||||
|
except ValueError:
|
||||||
|
# It wasn't a valid long!
|
||||||
|
irc.error(msg, '<seed> must be a valid int or long.')
|
||||||
|
return
|
||||||
|
self.rng.seed(seed)
|
||||||
|
irc.replySuccess()
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
So this one's a bit more complicated. But it's still pretty
|
||||||
|
simple. The method name is <botcommand>seed</botcommand> so
|
||||||
|
that'll be the command name. The arguments are the same, the
|
||||||
|
docstring is of the same form, so we don't need to go over
|
||||||
|
that again. The body of the function, however, is
|
||||||
|
significantly different.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<function>privmsgs.getArgs</function> is a function you're
|
||||||
|
going to be seeing a lot of when you write plugins for
|
||||||
|
supybot. What it does is basically give you the right number
|
||||||
|
of arguments for your comamnd. In this case, we want one
|
||||||
|
argument. But we might have been given any number of
|
||||||
|
arguments by the user. So
|
||||||
|
<function>privmsgs.getArgs</function> joins them
|
||||||
|
appropriately, leaving us with one single "seed" argument (by
|
||||||
|
default, it returns one argument as a single value; more
|
||||||
|
arguments are returned in a tuple/list). Yes, we could've
|
||||||
|
just said "seed = args[0]" and gotten the first argument, but
|
||||||
|
what if the user didn't pass us an argument at all? Then
|
||||||
|
we've got to catch the <classname>IndexError</classname> from
|
||||||
|
<varname>args[0]</varname> and complain to the user about it.
|
||||||
|
<function>privmsgs.getArgs</function>, on the other hand,
|
||||||
|
handles all that for us. If the user didn't give us enough
|
||||||
|
arguments, it'll reply with the help string for the command,
|
||||||
|
thus saving us the effort.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So we have the seed from
|
||||||
|
<function>privmsgs.getArgs</function>. But it's a string.
|
||||||
|
The next three lines is pretty darn obvious: we're just
|
||||||
|
converting the string to a int of some sort. But if it's not,
|
||||||
|
that's when we're going to call
|
||||||
|
<function>irc.error</function>. It has the same interface as
|
||||||
|
we saw before in <function>irc.reply</function>, but it makes
|
||||||
|
sure to remind the user that an error has been encountered
|
||||||
|
(currently, that means it puts <literal>"Error: "</literal> at
|
||||||
|
the beginning of the message). After erroring, we return.
|
||||||
|
It's important to remember this <keyword>return</keyword>
|
||||||
|
here; otherwise, we'll just keep going down through the
|
||||||
|
function and try to use this <varname>seed</varname> variable
|
||||||
|
that never got assigned. A good general rule of thumb is that
|
||||||
|
any time you use <function>irc.error</function>, you'll want
|
||||||
|
to return immediately afterwards.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Then we set the seed – that's a simple function on our
|
||||||
|
rng object. Assuming that succeeds (and doesn't raise an
|
||||||
|
exception, which it shouldn't, because we already read the
|
||||||
|
documentation and know that it should work) we reply to say
|
||||||
|
that everything worked fine. That's what
|
||||||
|
<function>irc.replySuccess</function> says. By default, it
|
||||||
|
has the very dry (and appropriately robot-like) "The operation
|
||||||
|
succeeded." but you're perfectly welcome to customize it
|
||||||
|
yourself – the registry was written to be modified!
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So that's a bit more complicated command. But we still
|
||||||
|
haven't dealt with multiple arguments. Let's do that
|
||||||
|
next.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So these random numbers are useful, but they're not the kind
|
||||||
|
of random numbers we usually want in Real Life. In Real Life,
|
||||||
|
we like to tell someone to "pick a number between 1 and 10."
|
||||||
|
So let's write a function that does that. Of course, we won't
|
||||||
|
hardcode the 1 or the 10 into the function, but we'll take
|
||||||
|
them as arguments. First the function:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def range(self, irc, msg, args):
|
||||||
|
"""<start> <end>
|
||||||
|
|
||||||
|
Returns a number between <start> and <end>, inclusive (i.e., the number
|
||||||
|
can be either of the endpoints.
|
||||||
|
"""
|
||||||
|
(start, end) = privmsgs.getArgs(args, required=2)
|
||||||
|
try:
|
||||||
|
end = int(end)
|
||||||
|
start = int(start)
|
||||||
|
except ValueError:
|
||||||
|
irc.error(msg, '<start> and <end> must both be integers.')
|
||||||
|
return
|
||||||
|
# .randrange() doesn't include the endpoint, so we use end+1.
|
||||||
|
irc.reply(msg, str(self.rng.randrange(start, end+1)))
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Pretty simple. This is becoming old hat by now. The only new
|
||||||
|
thing here is the call to
|
||||||
|
<function>privmsgs.getArgs</function>. We have to make sure,
|
||||||
|
since we want two values, to pass a keyword parameter
|
||||||
|
"required" into <function>privmsgs.getArgs</function>. Of
|
||||||
|
course, <function>privmsgs.getArgs</function> handles all the
|
||||||
|
checking for missing arguments and whatnot so we don't have
|
||||||
|
to.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <classname>Random</classname> object we're using offers us
|
||||||
|
a "sample" method that takes a sequence and a number (we'll
|
||||||
|
call it <varname>N</varname>) and returns a list of
|
||||||
|
<varname>N</varname> items taken randomly from the sequence.
|
||||||
|
So I'll show you an example that takes advantage of multiple
|
||||||
|
arguments but doesn't use
|
||||||
|
<function>privmsgs.getArgs</function> (and thus has to handle
|
||||||
|
its own errors if the number of arguments isn't right).
|
||||||
|
Here's the code:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def sample(self, irc, msg, args):
|
||||||
|
"""<number of items> [<text> ...]
|
||||||
|
|
||||||
|
Returns a sample of the <number of items> taken from the remaining
|
||||||
|
arguments. Obviously <number of items> must be less than the number
|
||||||
|
of arguments given.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
n = int(args.pop(0))
|
||||||
|
except IndexError: # raised by .pop(0)
|
||||||
|
raise callbacks.ArgumentError
|
||||||
|
except ValueError:
|
||||||
|
irc.error('<number of items> must be an integer.')
|
||||||
|
return
|
||||||
|
if n > len(args):
|
||||||
|
irc.error('<number of items> must be less than the number '
|
||||||
|
'of arguments.')
|
||||||
|
return
|
||||||
|
sample = self.rng.sample(args, n)
|
||||||
|
irc.reply(utils.commaAndify(map(repr, sample)))
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Most everything here is familiar. The difference between this
|
||||||
|
and the previous examples is that we're dealing with
|
||||||
|
<varname>args</varname> directly, rather than through
|
||||||
|
<function>getArgs</function>. Since we already have the
|
||||||
|
arguments in a list, it doesn't make any sense to have
|
||||||
|
<function>privmsgs.getArgs</function> smush them all together
|
||||||
|
into a big long string that we'll just have to re-split. But
|
||||||
|
we still want the nice error handling of
|
||||||
|
<function>privmsgs.getArgs</function>. So what do we do? We
|
||||||
|
raise <classname>callbacks.ArgumentError</classname>! That's
|
||||||
|
the secret juju that <function>privmsgs.getArgs</function> is
|
||||||
|
doing; now we're just doing it ourself. Someone up our
|
||||||
|
callchain knows how to handle it so a neat error message is
|
||||||
|
returned. So in this function, if
|
||||||
|
<function>.pop(0)</function> fails, we weren't given enough
|
||||||
|
arguments and thus need to tell the user how to call us.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So we have the args, we have the number, we do a simple call
|
||||||
|
to <function>random.sample</function> and then we do this
|
||||||
|
funky <function>utils.commaAndify</function> to it. Yeah, so
|
||||||
|
I was running low on useful names :) Anyway, what it does is
|
||||||
|
take a list of strings and return a string with them joined by
|
||||||
|
a comma, the last one being joined with a comma and "and". So
|
||||||
|
the list ['foo', 'bar', 'baz'] becomes "foo, bar, and baz".
|
||||||
|
It's pretty useful for showing the user lists in a useful
|
||||||
|
form. We map the strings with <function>repr()</function>
|
||||||
|
first just to surround them with quotes.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So we have one more example. Yes, I hear your groans, but
|
||||||
|
it's pedagogically useful :) This time we're going to write a
|
||||||
|
command that makes the bot roll a die. It'll take one
|
||||||
|
argument (the number of sides on the die) and will respond
|
||||||
|
with the equivalent of "/me rolls a __" where __ is the number
|
||||||
|
the bot rolled. So here's the code:
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
def diceroll(self, irc, msg, args):
|
||||||
|
"""[<number of sides>]
|
||||||
|
|
||||||
|
Rolls a die with <number of sides> sides. The default number
|
||||||
|
of sides is 6.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
n = privmsgs.getArgs(args, required=0, optional=1)
|
||||||
|
if not n:
|
||||||
|
n = 6
|
||||||
|
n = int(n)
|
||||||
|
except ValueError:
|
||||||
|
irc.error(msg, 'Dice have integer numbers of sides. Use one.')
|
||||||
|
return
|
||||||
|
s = 'rolls a %s' % self.rng.randrange(1, n+1)
|
||||||
|
irc.reply(s, action=True)
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
There's a lot of stuff you haven't seen before in there. The
|
||||||
|
most important, though, is the first thing you'll notice
|
||||||
|
that's different: the <function>privmsg.getArgs</function>
|
||||||
|
call. Here we're offering a default argument in case the user
|
||||||
|
is too lazy to supply one (or just wants a nice, standard
|
||||||
|
six-sided die :)) <function>privmsgs.getArgs</function>
|
||||||
|
supports that; we'll just tell it that we don't
|
||||||
|
<emphasis>need</emphasis> any arguments (via
|
||||||
|
<varname>required=0</varname>) and that we <emphasis>might
|
||||||
|
like</emphasis> one argument (<varname>optional=1</varname>).
|
||||||
|
If the user provides an argument, we'll get it -- if they
|
||||||
|
don't, we'll just get an empty string. Hence the "if not n: n
|
||||||
|
= 6", where we provide the default.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You'll also note that <function>irc.reply</function> was given
|
||||||
|
a keyword argument here, <varname>action</varname>. This
|
||||||
|
means that the reply is to be made as an action rather than a
|
||||||
|
normal reply.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
So that's our plugin. 5 commands, each building in
|
||||||
|
complexity. You should now be able to write most anything you
|
||||||
|
want to do in Supybot. Except regexp-based plugins, but
|
||||||
|
that's a story for another day (and those aren't nearly as
|
||||||
|
cool as these command-based callbacks anyway :)). Now we need
|
||||||
|
to flesh it out to make it a full-fledged plugin.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2>
|
||||||
|
<title>Using the registry in your plugin</title>
|
||||||
|
<para>
|
||||||
|
TODO: Describe the registry and how to write a proper plugin
|
||||||
|
configure function.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<para>
|
||||||
|
We've written our own plugin from scratch (well, from the
|
||||||
|
boilerplate that we got from
|
||||||
|
<script>scripts/newplugin.py</script> :)) and
|
||||||
|
survived! Now go write more plugins for supybot, and send
|
||||||
|
them to me so I can use them too :)
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</article>
|
||||||
46
docs/DocBook/supybot-html.dsl
Normal file
46
docs/DocBook/supybot-html.dsl
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
(define %stylesheet% "../stylesheets/supybot.css")
|
||||||
|
|
||||||
|
(element botcommand
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "botcommand"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element plugin
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "plugin"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element flag
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "flag"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element nick
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "nick"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element capability
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "capability"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element registrygroup
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "registrygroup"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element ircsession
|
||||||
|
(make element gi: "pre"
|
||||||
|
attributes: '(("class" "ircsession"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element script
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "script"))
|
||||||
|
(process-children)))
|
||||||
|
|
||||||
|
(element channel
|
||||||
|
(make element gi: "span"
|
||||||
|
attributes: '(("class" "channel"))
|
||||||
|
(process-children)))
|
||||||
43
docs/DocBook/supybot-print.dsl
Normal file
43
docs/DocBook/supybot-print.dsl
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
(define %mono-font-family% "Courier New")
|
||||||
|
|
||||||
|
(element botcommand
|
||||||
|
(make sequence
|
||||||
|
font-family-name: %mono-font-family%))
|
||||||
|
|
||||||
|
(element plugin
|
||||||
|
(make sequence
|
||||||
|
font-weight: 'bold))
|
||||||
|
|
||||||
|
(element flag
|
||||||
|
(make sequence
|
||||||
|
font-posture: 'italic))
|
||||||
|
|
||||||
|
(element nick
|
||||||
|
(make sequence
|
||||||
|
font-family-name: %mono-font-family%))
|
||||||
|
|
||||||
|
(element capability
|
||||||
|
(make sequence
|
||||||
|
font-weight: 'bold))
|
||||||
|
|
||||||
|
(element registrygroup
|
||||||
|
(make sequence
|
||||||
|
font-weight: 'bold))
|
||||||
|
|
||||||
|
(element ircsession
|
||||||
|
(make paragraph
|
||||||
|
font-family-name: %mono-font-family%
|
||||||
|
space-before: 12pt
|
||||||
|
space-after: 12pt
|
||||||
|
start-indent: 6pt
|
||||||
|
lines: 'asis
|
||||||
|
input-whitespace-treatment: 'preserve))
|
||||||
|
|
||||||
|
(element script
|
||||||
|
(make sequence
|
||||||
|
font-family-name: %mono-font-family%))
|
||||||
|
|
||||||
|
(element channel
|
||||||
|
(make sequence
|
||||||
|
font-weight: 'bold))
|
||||||
|
|
||||||
41
docs/DocBook/supybot.css
Normal file
41
docs/DocBook/supybot.css
Normal file
@ -0,0 +1,41 @@
|
|||||||
|
.channel {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
.botcommand {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.flag {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.nick {
|
||||||
|
font-style: italic;
|
||||||
|
}
|
||||||
|
|
||||||
|
.plugin {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.capability {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.registrygroup {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.ircsession {
|
||||||
|
font-family: monospace;
|
||||||
|
display: block;
|
||||||
|
background-color: #666666;
|
||||||
|
}
|
||||||
|
|
||||||
|
.script {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
|
.channel {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
23
docs/DocBook/supybot.dsl
Normal file
23
docs/DocBook/supybot.dsl
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
||||||
|
<!ENTITY print-ss PUBLIC
|
||||||
|
"-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
|
||||||
|
<!ENTITY html-ss PUBLIC
|
||||||
|
"-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
|
||||||
|
<!ENTITY supybot-print SYSTEM "supybot-print.dsl">
|
||||||
|
<!ENTITY supybot-html SYSTEM "supybot-html.dsl">
|
||||||
|
]>
|
||||||
|
|
||||||
|
<style-sheet>
|
||||||
|
<style-specification id="print" use="print-stylesheet">
|
||||||
|
<style-specification-body>
|
||||||
|
&supybot-print;
|
||||||
|
</style-specification-body>
|
||||||
|
</style-specification>
|
||||||
|
<style-specification id="html" use="html-stylesheet">
|
||||||
|
<style-specification-body>
|
||||||
|
&supybot-html;
|
||||||
|
</style-specification-body>
|
||||||
|
</style-specification>
|
||||||
|
<external-specification id="print-stylesheet" document="print-ss">
|
||||||
|
<external-specification id="html-stylesheet" document="html-ss">
|
||||||
|
</style-sheet>
|
||||||
139
docs/DocBook/supybot.dtd
Normal file
139
docs/DocBook/supybot.dtd
Normal file
@ -0,0 +1,139 @@
|
|||||||
|
<!-- Segregate all of our stuff into its own class for possible extension
|
||||||
|
later and just because I wanted to write my own class :) -->
|
||||||
|
<!ENTITY % local.supybot.tech.char.class "">
|
||||||
|
<!ENTITY % supybot.tech.char.class "BotCommand|Plugin|Flag|Nick|Capability
|
||||||
|
|RegistryGroup|Registry|Script
|
||||||
|
|Channel %local.supybot.tech.char.class;">
|
||||||
|
|
||||||
|
<!-- Stuff that isn't supybot-specific, but it's python-related and no
|
||||||
|
suitable element exists in the DocBook DTD -->
|
||||||
|
<!ENTITY % local.python.tech.char.class "">
|
||||||
|
<!ENTITY % python.tech.char.class "Module|Keyword
|
||||||
|
%local.python.tech.char.class;">
|
||||||
|
|
||||||
|
<!-- Pretty much all of our stuff fits where stuff in the tech.char class
|
||||||
|
goes, so we simply add our stuff using the local extension -->
|
||||||
|
<!ENTITY % local.tech.char.class "|%supybot.tech.char.class;
|
||||||
|
|%python.tech.char.class;">
|
||||||
|
|
||||||
|
<!-- linespecific is the same class as things like screen and programlisting,
|
||||||
|
so it's added here to fit with the DocBook stuff (i.e., so putting an
|
||||||
|
ircsession in where one of those previous two elements would be is a
|
||||||
|
valid operation -->
|
||||||
|
<!ENTITY % local.linespecific.class "|IrcSession">
|
||||||
|
|
||||||
|
<!-- Source the original DocBook DTD -->
|
||||||
|
<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||||
|
%DocBookDTD;
|
||||||
|
|
||||||
|
<!ELEMENT BotCommand - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.botcommand.attrib "">
|
||||||
|
<!ENTITY % botcommand.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST BotCommand
|
||||||
|
%common.attrib;
|
||||||
|
%local.botcommand.attrib;
|
||||||
|
%botcommand.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Plugin - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.plugin.attrib "">
|
||||||
|
<!ENTITY % plugin.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Plugin
|
||||||
|
%common.attrib;
|
||||||
|
%local.plugin.attrib;
|
||||||
|
%plugin.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Flag - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.flag.attrib "">
|
||||||
|
<!ENTITY % flag.role.attrib
|
||||||
|
"
|
||||||
|
flagtype (arg|noarg) #IMPLIED
|
||||||
|
%role.attrib;"
|
||||||
|
>
|
||||||
|
<!ATTLIST Flag
|
||||||
|
%common.attrib;
|
||||||
|
%local.flag.attrib;
|
||||||
|
%flag.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Nick - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.nick.attrib "">
|
||||||
|
<!ENTITY % nick.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Nick
|
||||||
|
%common.attrib;
|
||||||
|
%local.nick.attrib;
|
||||||
|
%nick.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Capability - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.capability.attrib "">
|
||||||
|
<!ENTITY % capability.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Capability
|
||||||
|
%common.attrib;
|
||||||
|
%local.capability.attrib;
|
||||||
|
%capability.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Comment - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.comment.attrib "">
|
||||||
|
<!ENTITY % comment.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Comment
|
||||||
|
%common.attrib;
|
||||||
|
%local.comment.attrib;
|
||||||
|
%comment.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT RegistryGroup - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.registrygroup.attrib "">
|
||||||
|
<!ENTITY % registrygroup.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST RegistryGroup
|
||||||
|
%common.attrib;
|
||||||
|
%local.registrygroup.attrib;
|
||||||
|
%registrygroup.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Registry - - ((RegistryGroup|Comment)+)>
|
||||||
|
<!ENTITY % local.registry.attrib "">
|
||||||
|
<!ENTITY % registry.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Registry
|
||||||
|
%common.attrib;
|
||||||
|
%local.registry.attrib;
|
||||||
|
%registry.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT IrcSession - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.ircsession.attrib "">
|
||||||
|
<!ENTITY % ircsession.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST IrcSession
|
||||||
|
%common.attrib;
|
||||||
|
%local.ircsession.attrib;
|
||||||
|
%ircsession.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Script - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.script.attrib "">
|
||||||
|
<!ENTITY % script.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Script
|
||||||
|
%common.attrib;
|
||||||
|
%local.script.attrib;
|
||||||
|
%script.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Channel - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.channel.attrib "">
|
||||||
|
<!ENTITY % channel.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Channel
|
||||||
|
%common.attrib;
|
||||||
|
%local.channel.attrib;
|
||||||
|
%channel.role.attrib;
|
||||||
|
>
|
||||||
|
|
||||||
|
<!ELEMENT Module - - ((%smallcptr.char.mix)+)>
|
||||||
|
<!ENTITY % local.module.attrib "">
|
||||||
|
<!ENTITY % module.role.attrib "%role.attrib;">
|
||||||
|
<!ATTLIST Module
|
||||||
|
%common.attrib;
|
||||||
|
%local.module.attrib;
|
||||||
|
%module.role.attrib;
|
||||||
|
>
|
||||||
240
docs/FAQ
Normal file
240
docs/FAQ
Normal file
@ -0,0 +1,240 @@
|
|||||||
|
Q: Why does my bot not recognize me or tell me that I don't have the
|
||||||
|
"owner" capability?
|
||||||
|
|
||||||
|
A: Because you've not given it anything to recognize you from!
|
||||||
|
You'll need to identify with the bot ("help identify" to see how
|
||||||
|
that works) or add your hostmask to your user record ("help
|
||||||
|
addhostmask" to see how that works) for it to know that you're you.
|
||||||
|
You may wish to note that addhostmask can accept a password; rather
|
||||||
|
than identify, you can send the command "addhostmask myOwnerUser
|
||||||
|
[hostmask] myOwnerUserPassword" and the bot will add your current
|
||||||
|
hostmask to your owner user (of course, you should change
|
||||||
|
myOwnerUser and myOwnerUserPassword appropriately for your bot).
|
||||||
|
|
||||||
|
|
||||||
|
Q: What's a hostmask?
|
||||||
|
|
||||||
|
A: Each user on IRC is uniquely identified by a string which we call
|
||||||
|
a "hostmask." The IRC RFC refers to it as a prefix. Either way,
|
||||||
|
it consists of a nick, a user, and a host, in the form
|
||||||
|
nick!user@host. If your Supybot complains that something you've
|
||||||
|
given to it isn't a hostmask, make sure that you have those three
|
||||||
|
components and that they're joined in the appropriate manner.
|
||||||
|
|
||||||
|
|
||||||
|
Q: How do I make my Supybot op my users?
|
||||||
|
|
||||||
|
A: First, you'll have to make sure that your users register with the
|
||||||
|
bot. They can do this with the "register" command. After they do
|
||||||
|
so, you'll want to add the #channel,op capability to their user.
|
||||||
|
Use the "channel addcapability" command to do this. After that,
|
||||||
|
your users should be able to use the "op" command to get ops.
|
||||||
|
|
||||||
|
If you want your users to be auto-opped when they join the channel,
|
||||||
|
you'll need to load the Enforcer plugin and turn its autoOp
|
||||||
|
configuration variable on. Use the "config" command to do so.
|
||||||
|
Here's an example of how to do these steps:
|
||||||
|
|
||||||
|
<jemfinch> I'm going to make an example session for giving
|
||||||
|
you auto-ops, for our FAQ.
|
||||||
|
<dunk1> ah ok ;]
|
||||||
|
<jemfinch> First, I need you to register with supybot, using
|
||||||
|
the "register" command (remember to send it in
|
||||||
|
private).
|
||||||
|
<dunk1> done
|
||||||
|
<jemfinch> what name are you registered under?
|
||||||
|
<dunk1> dunk1
|
||||||
|
<jemfinch> ok, cool.
|
||||||
|
<jemfinch> @channel addcapability dunk1 op
|
||||||
|
<supybot> jemfinch: The operation succeeded.
|
||||||
|
<jemfinch> now use the "op" command to get ops.
|
||||||
|
<dunk1> @op
|
||||||
|
--- supybot gives channel operator status to dunk1
|
||||||
|
<dunk1> works!
|
||||||
|
<dunk1> ;]
|
||||||
|
<jemfinch> @load Enforcer
|
||||||
|
<supybot> jemfinch: The operation succeeded.
|
||||||
|
<jemfinch> @config channel supybot.plugins.Enforcer.autoOp On
|
||||||
|
<supybot> jemfinch: The operation succeeded.
|
||||||
|
<jemfinch> ok, now cycle the channel (part and then rejoin)
|
||||||
|
<-- dunk1 (dunker@freebsd.nl) has left #supybot
|
||||||
|
--> dunk1 (dunker@freebsd.nl) has joined #supybot
|
||||||
|
--- supybot gives channel operator status to dunk1
|
||||||
|
<jemfinch> cool, thanks :)
|
||||||
|
|
||||||
|
|
||||||
|
Q: Can users with the "admin" capability change configuration
|
||||||
|
variables?
|
||||||
|
|
||||||
|
A: Currently, no. Feel free to make your case to us as to why a
|
||||||
|
certain configuration variable should only require the "admin"
|
||||||
|
capability instead of the "owner" capability, and if we agree
|
||||||
|
with you, we'll change it for the next release.
|
||||||
|
|
||||||
|
|
||||||
|
Q: Can Supybot do factoids?
|
||||||
|
|
||||||
|
A: Supybot most certainly can! In fact, we offer three full-fledged
|
||||||
|
factoids-related plugins!
|
||||||
|
|
||||||
|
Factoids (written by jemfinch) is Supybot's original
|
||||||
|
factoids-related plugin. It offers full integration with Supybot's
|
||||||
|
nested commands as well as a complete 1:n key to factoid ratio,
|
||||||
|
with lookup by individual number. Factoids also uses a
|
||||||
|
channel-specific database instead of a global database, though
|
||||||
|
that's configurable with the
|
||||||
|
supybot.databases.plugins.channelSpecific configuration variable.
|
||||||
|
|
||||||
|
MoobotFactoids (written by Strike) is much more full-featured,
|
||||||
|
offering users the ability to define factoids in a slightly more
|
||||||
|
user-friendly way, as well as parsing factoids to handle <reply>,
|
||||||
|
<action>, and alternations (defining a factoid "test" as
|
||||||
|
"<reply>(foo|bar|baz)" will make the bot send "foo" or "bar" or
|
||||||
|
"baz" to the channel (without the normal "test is " at the
|
||||||
|
beginning)). If you're accustomed to Moobot's factoids or
|
||||||
|
Blootbot's factoids, then this is the Factoids plugin for you.
|
||||||
|
Unfortunately, due to the more natural definition syntax (required
|
||||||
|
to be compatible with Moobot) you can't define Factoids with nested
|
||||||
|
commands; you'll have to evaluate the command first and then copy
|
||||||
|
the result into your factoid definition.
|
||||||
|
|
||||||
|
Infobot (written by jamessan) is used for Infobot compatibility;
|
||||||
|
if you still want the basic functionality of Infobot, this is the
|
||||||
|
plugin to use.
|
||||||
|
|
||||||
|
|
||||||
|
Q: Can I import my Infobot/Blootbot/Moobot factoids into Supybot?
|
||||||
|
|
||||||
|
A: As of present, we have no automated way to do so. Strike has
|
||||||
|
written a few scripts for importing a Moobot database into
|
||||||
|
MoobotFactoids, however, so you'll want to talk to him about
|
||||||
|
helping you with that. We're certainly happy to help you convert
|
||||||
|
such databases; if you can provide us with such a database exported
|
||||||
|
to a flat file, we can probably do the rest of the work to write a
|
||||||
|
script that imports it into a database for one of our
|
||||||
|
factoids-related plugins.
|
||||||
|
|
||||||
|
|
||||||
|
Q: Do I really have to use separate databases for each channel?
|
||||||
|
|
||||||
|
A: Of course not! We default to separate databases for each channel
|
||||||
|
because, well, that's what jemfinch always thought was
|
||||||
|
reasonable. Anyway, if you change the configuration variable
|
||||||
|
supybot.databases.plugins.channelSpecific to False instead of
|
||||||
|
True, for *most* databases, each channel will share the same
|
||||||
|
database (the exceptions are ChannelStats, Herald, Seen, and
|
||||||
|
WordStats, which are inherently rather channel-based).
|
||||||
|
|
||||||
|
|
||||||
|
Q: Karma doesn't seem to work for me.
|
||||||
|
|
||||||
|
A: Karma by default doesn't acknowledge karma updates. If you check
|
||||||
|
the karma of whatever you increased/decreased, you'll note that
|
||||||
|
your increment or decrement still took place. If you'd rather
|
||||||
|
Karma acknowledge karma updates, change the
|
||||||
|
supybot.plugins.Karma.response configuration variable to On.
|
||||||
|
|
||||||
|
|
||||||
|
Q: I added an alias, but it doesn't work!
|
||||||
|
|
||||||
|
A: Take a look at "help <alias you added>". If the alias the bot has
|
||||||
|
listed doesn't match what you're giving it, chances are you need
|
||||||
|
to quote your alias in order for the brackets not to be
|
||||||
|
evaluated. For instance, if you're adding an alias to give you a
|
||||||
|
link to your homepage, you need to say:
|
||||||
|
|
||||||
|
alias add mylink "format concat http://my.host.com/ [urlquote $1]"
|
||||||
|
|
||||||
|
and not:
|
||||||
|
|
||||||
|
alias add mylink format concat http://my.host.com/ [urlquote $1]
|
||||||
|
|
||||||
|
The first version works; the second version will always return the
|
||||||
|
same url.
|
||||||
|
|
||||||
|
Q: Is there a command that can tell me what capability another
|
||||||
|
command requires?
|
||||||
|
|
||||||
|
A: No, there isn't, and there probably never will be. Commands have
|
||||||
|
the flexibility to check any capabilities they wish to check;
|
||||||
|
while this flexibility is useful, it also makes it hard to guess
|
||||||
|
what capability a certain command requires. We could make a
|
||||||
|
solution that would work in a large majority of cases, but it
|
||||||
|
wouldn't (and couldn't!) be absolutely correct in all
|
||||||
|
circumstances, and since we're anal and we hate doing things
|
||||||
|
halfway, we probably won't ever add this partial solution.
|
||||||
|
|
||||||
|
Besides, is the error message so bad? If we did have such a
|
||||||
|
command, many users would call the command, see that they could
|
||||||
|
perform it, and then run the command, thus doubling the activity
|
||||||
|
in the channel. Is that something you want?
|
||||||
|
|
||||||
|
|
||||||
|
Q: How do I make my Supybot connect to multiple servers?
|
||||||
|
|
||||||
|
A: Just use the "connect" command in the Network plugin. Easy as pie!
|
||||||
|
|
||||||
|
|
||||||
|
Q: My bot can't handle nicks with brackets in them! It always
|
||||||
|
complains about something not being a valid command, or about
|
||||||
|
spurious or missing right brackets, etc.
|
||||||
|
|
||||||
|
A: You should quote arguments (using double quotes, like this:
|
||||||
|
"foo[bar]") that have brackets in them that you don't wish to be
|
||||||
|
evaluated as nested commands. Otherwise, you can turn off nested
|
||||||
|
commands by setting supybot.commands.nested to False, or change
|
||||||
|
the brackets that nest commands, by setting
|
||||||
|
supybot.commands.nested.brackets to some other value (like <>,
|
||||||
|
which can't occur in IRC nicks).
|
||||||
|
|
||||||
|
|
||||||
|
Q: I've edited my configuration file, but my Supybot doesn't notice
|
||||||
|
the changes! Even if I restart it, it doesn't see them. What's
|
||||||
|
the deal?
|
||||||
|
|
||||||
|
A: Supybot won't reload its configuration files unless you tell it
|
||||||
|
to. In addition, when Supybot exits (and periodically while it
|
||||||
|
runs) it flushes its configuration file to disk. The safest way
|
||||||
|
to avoid problems with configuration file edits is simply to exit
|
||||||
|
the bot before editing the configuration file(s). If you don't
|
||||||
|
wish to do that, however, you can edit the file, save the changes,
|
||||||
|
and tell the bot to reload its configuration, either via the
|
||||||
|
reload command in the Config plugin, or by sending the bot a
|
||||||
|
SIGHUP. There is a brief period in this whole sequence where the
|
||||||
|
bot can flush its configuration to disk after you write your
|
||||||
|
changes, but we even have something to fix that: set the
|
||||||
|
configuration variable supybot.flush to False, and then reload the
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
|
||||||
|
Q: I found a bug, what do I do?
|
||||||
|
|
||||||
|
A: Submit it on Sourceforge through our Sourceforge project page:
|
||||||
|
<http://sourceforge.net/tracker/?group_id=58965&atid=489447>. If
|
||||||
|
Sourceforge happens to be down when you try to submit your bug,
|
||||||
|
then post it in the "Supybot Developer Discussion" forum at our
|
||||||
|
forums at <http://forums.supybot.org/>. If that doesn't work,
|
||||||
|
email supybot-bugs@lists.sourceforge.net. If that doesn't work,
|
||||||
|
email jemfinch@supybot.org. If that doesn't work, find yourself
|
||||||
|
some carrier pigeons and ... hah! You thought I was serious!
|
||||||
|
|
||||||
|
Anyway, when you submit your bug, we'll need several things. If
|
||||||
|
the bug involved an uncaught exception, we need the traceback
|
||||||
|
(basically the stuff from "Uncaught exception in ..." to the next
|
||||||
|
log entry). We'd also like to see the commands that caused the
|
||||||
|
bug, or happened around the time you saw the bug. If the bug
|
||||||
|
involved a database, we'd love to see the database. Remember, it's
|
||||||
|
always worse to send us too little information in a bug report than
|
||||||
|
too much.
|
||||||
|
|
||||||
|
|
||||||
|
Q: Is there a way just to load *all* the plugins Supybot has?
|
||||||
|
|
||||||
|
A: No, there isn't. Even if there were, some plugins conflict with
|
||||||
|
other plugins, so it wouldn't make much sense to load them. For
|
||||||
|
instance, what would a bot do with Factoids, MoobotFactoids, and
|
||||||
|
Infobot all loaded? Probably just annoy people :)
|
||||||
|
|
||||||
|
If you want to know more about the plugins that are available,
|
||||||
|
check out our "Plugin index" at our website.
|
||||||
|
|
||||||
71
docs/FIXING-BUGS
Normal file
71
docs/FIXING-BUGS
Normal file
@ -0,0 +1,71 @@
|
|||||||
|
These are a list of recurrent bugs in Supybot, and ways to notice
|
||||||
|
them. It just might come in useful for people maintaining code.
|
||||||
|
|
||||||
|
1. Using == or != when you mean ircutils.strEqual. Nicks, prefixes,
|
||||||
|
and channels should be compared for equality not by == or !=, but
|
||||||
|
by ircutils.strEqual. This does a case-normalized check. Don't
|
||||||
|
just use lower() because that doesn't use the rfc1459 casemapping.
|
||||||
|
|
||||||
|
To find:
|
||||||
|
grep == plugins/*.py | egrep "nick|channel"
|
||||||
|
grep "!=" plugins/*.py | egrep "nick|channel"
|
||||||
|
|
||||||
|
2. Using a warning log when it really should be an info log. Users
|
||||||
|
don't like to see warnings. If we have warning logs, they'll
|
||||||
|
complain. So let's try to make them complain as little as
|
||||||
|
possible, and only use warnings when you've encountered a *very*
|
||||||
|
odd situation, or when you need more information before
|
||||||
|
determining if something is correct.
|
||||||
|
|
||||||
|
An example: The Services plugin has two methods, doNickservNotice
|
||||||
|
and doChanservNotice, which doNotice dispatches to appropriately.
|
||||||
|
Now, we can't possibly predict all the possible messages that
|
||||||
|
ChanServ or NickServ might send to us. So I put a default clause
|
||||||
|
in there that just says, "Hey, this is an unexpected message from
|
||||||
|
ChanServ/NickServ: ..." I log this at warning level because I
|
||||||
|
want to know when there's a NickServ/ChanServ message I haven't
|
||||||
|
seen before. This works: the warning makes users report it.
|
||||||
|
|
||||||
|
Another example: We used to log failures in snarfers at the
|
||||||
|
warning level. But do the users really want to be warned when a
|
||||||
|
given "url" isn't valid? No! So now we just make it an info log,
|
||||||
|
so that users who care can still see why a snarfer didn't snarf,
|
||||||
|
but no one complains to us about it.
|
||||||
|
|
||||||
|
To find:
|
||||||
|
grep log.warning plugins/*.py
|
||||||
|
|
||||||
|
3. Spelling errors. They plague almost every large piece of
|
||||||
|
software. Supybot is no different, but we have a weapon against
|
||||||
|
them: find-strings.py. Give find-strings.py a set of files, and
|
||||||
|
it'll extract all the non-raw literal strings from the source code
|
||||||
|
and output them to a file, with the originating file, line number,
|
||||||
|
and string. Spell-checking Supybot is just a matter of taking
|
||||||
|
this 10,000 line file and an hour and running aspell over it,
|
||||||
|
correcting the errors in the original file as you find them.
|
||||||
|
|
||||||
|
To find:
|
||||||
|
find-strings.py src/*.py plugins/*.py scripts/supybot*
|
||||||
|
|
||||||
|
4. Pegging the CPU. It has happened in the past that bugs in Supybot
|
||||||
|
have caused 100% CPU usage. These are insidious, and generally
|
||||||
|
hard to track down. Here are our tools against them; we assuming
|
||||||
|
that the bug is reproducible.
|
||||||
|
|
||||||
|
First, I load the Debug plugin and settrace to a file, then I
|
||||||
|
quickly reproduce the bug, and let the CPU spin for awhile. Then
|
||||||
|
I kill the bot and check the trace file (which should be large).
|
||||||
|
I look for patterns that would indicate an infinite loop of some
|
||||||
|
sort.
|
||||||
|
|
||||||
|
Second, I strace the bot when it's looping. If I see output, it's
|
||||||
|
making syscalls; if I don't see any output, it's not. If it's
|
||||||
|
making syscalls, that might mean it's looping in the network
|
||||||
|
drivers somehow; if not, it's somewhere else.
|
||||||
|
|
||||||
|
Third, I check that no regexps could be causing it. They're
|
||||||
|
notorious for appearing safe, but actually hiding exponential
|
||||||
|
complexity code (the kind of code that strong cryptography is
|
||||||
|
based on).
|
||||||
|
|
||||||
|
After that, I pray harder :)
|
||||||
143
docs/GETTING_STARTED
Normal file
143
docs/GETTING_STARTED
Normal file
@ -0,0 +1,143 @@
|
|||||||
|
Ok, so you've decided to try out Supybot. That's great! The more
|
||||||
|
people who use Supybot, the more people can submit bugs and help us to
|
||||||
|
make it the best IRC bot in the world :)
|
||||||
|
|
||||||
|
First things first. You should have already read through INSTALL
|
||||||
|
before reading any further.
|
||||||
|
|
||||||
|
Ok, so let's assume your bot connected to the server fine and joined
|
||||||
|
the channels you told it to join. For now we'll assume you named your
|
||||||
|
bot "supybot" (you probably didn't, but it'll make it much clearer in
|
||||||
|
the examples that follow to assume that you did). We'll also assume
|
||||||
|
that you told it to join #channel (a nice generic name for a channel,
|
||||||
|
isn't it? :)) So what do you do with this bot that you just made to
|
||||||
|
join your channel? Try this in the channel:
|
||||||
|
|
||||||
|
supybot: list
|
||||||
|
|
||||||
|
Replacing "supybot" with the actual name you picked for your bot, of
|
||||||
|
course. Your bot should reply with a list of the plugins he currently
|
||||||
|
has loaded. At least Admin, Channel, Config, Misc, Owner, and User
|
||||||
|
should be there; if you used supybot-wizard to create your
|
||||||
|
configuration file you may have many more plugins loaded. The list
|
||||||
|
command can also be used to list the commands in a given plugin:
|
||||||
|
|
||||||
|
supybot: list Misc
|
||||||
|
|
||||||
|
Will list all the commands in the Misc plugin. If you want to see the
|
||||||
|
help for any command, just use the help command:
|
||||||
|
|
||||||
|
supybot: help help
|
||||||
|
supybot: help list
|
||||||
|
supybot: help load
|
||||||
|
|
||||||
|
Sometimes more than one plugin will have a given command; for
|
||||||
|
instance, the "list" command exists in both the Misc and Config
|
||||||
|
plugins (both loaded by default). List, in this case, defaults to the
|
||||||
|
Misc plugin, but you may want to get the help for the list command in
|
||||||
|
the Config plugin. In that case, you'll want to give your command
|
||||||
|
like this:
|
||||||
|
|
||||||
|
supybot: help config list
|
||||||
|
|
||||||
|
Anytime your bot tells you that a given command is defined in several
|
||||||
|
plugins, you'll want to use this syntax ("plugin command") to
|
||||||
|
disambiguate which plugin's command you wish to call. For instance,
|
||||||
|
if you wanted to call the Config plugin's list command, then you'd
|
||||||
|
need to say:
|
||||||
|
|
||||||
|
supybot: config list
|
||||||
|
|
||||||
|
Rather than just "list".
|
||||||
|
|
||||||
|
Now that you know how to deal with plugins having commands with the
|
||||||
|
same name, let's take a look at loading other plugins. If you didn't
|
||||||
|
use supybot-wizard, though, you might do well to try it before playing
|
||||||
|
around with loading plugins yourself: each plugin has its own
|
||||||
|
configure function that the wizard uses to setup the appropriate
|
||||||
|
registry entries if the plugin requires any.
|
||||||
|
|
||||||
|
Now, if you do want to play around with loading plugins, you're going
|
||||||
|
to need to have the owner capability. If you ran the wizard, then
|
||||||
|
chances are you already added an owner user for yourself. If not,
|
||||||
|
however, you can add one via the handy-dandy supybot-adduser script.
|
||||||
|
You'll want to run it while the bot is not running (otherwise it could
|
||||||
|
overwrite supybot-adduser's changes to your user database before you
|
||||||
|
get a chance to reload them). Just follow the prompts, and when it
|
||||||
|
asks if you want to give the user any capabilities, say yes and then
|
||||||
|
give yourself the "owner" capability (without the quotes), restart the
|
||||||
|
bot and you'll be ready to load some plugins!
|
||||||
|
|
||||||
|
Now, in order for the bot to recognize you as your owner user, you'll
|
||||||
|
have to identify with the bot. Open up a query window in your irc
|
||||||
|
client (/query should do it; if not, just know that you can't identify
|
||||||
|
in a channel because it requires sending your password to the bot).
|
||||||
|
Then type this:
|
||||||
|
|
||||||
|
help identify
|
||||||
|
|
||||||
|
And follow the instructions; the command you send will probably look
|
||||||
|
like this, with your owner user and password replaced:
|
||||||
|
|
||||||
|
identify myowneruser myuserpassword
|
||||||
|
|
||||||
|
The bot will tell you that "The operation succeeded" if you got the
|
||||||
|
right name and password. Now that you're identified, you can do
|
||||||
|
anything that requires any privilege: that includes all the commands
|
||||||
|
in the Owner and Admin plugins, which you may want to take a look at
|
||||||
|
(using the list and help commands, of course). One command in
|
||||||
|
particular that you might want to use (it's from the User plugin) is
|
||||||
|
the addhostmask command: it lets you add a hostmask to your user
|
||||||
|
record so the bot recognizes you by your hostmask instead of requiring
|
||||||
|
you to always identify with it before it recognizes you. Use the help
|
||||||
|
command to see how this command works. Here's how I often use it:
|
||||||
|
|
||||||
|
addhostmask myuser [hostmask] mypassword
|
||||||
|
|
||||||
|
You may not have seen that "[hostmask]" syntax before. Supybot allows
|
||||||
|
nested commands, which means that any command's output can be nested
|
||||||
|
as an argument to another command. The hostmask command from the Misc
|
||||||
|
plugin returns the hostmask of a given nick, but if given no
|
||||||
|
arguments, it returns the hostmask of the person giving the command.
|
||||||
|
So the command above adds the hostmask I'm currently using to my
|
||||||
|
user's list of recognized hostmasks. I'm only required to give
|
||||||
|
mypassword if I'm not already identified with the bot.
|
||||||
|
|
||||||
|
Now, with all that out of the way, we can continue telling you how to
|
||||||
|
load plugins :) Remember earlier when I told you to try "help
|
||||||
|
load"? That's the very command you'll be using. Basically, if you
|
||||||
|
want to load, say, the Fun plugin, then "load Fun". Simple, right?
|
||||||
|
If you need a list of the plugins you can load, you'll have to either
|
||||||
|
list the directory the plugins are in, or you'll have to check our
|
||||||
|
website -- look for the "Plugin index."
|
||||||
|
|
||||||
|
Another command you might find yourself needing somewhat often is the
|
||||||
|
"more" command. The IRC protocol limits messages to 512 bytes, 60 or
|
||||||
|
so of which must be devoted to some bookkeeping. Sometimes, however,
|
||||||
|
Supybot wants to send a message that's longer than that. What it
|
||||||
|
does, then, is break it into "chunks" and send the first one,
|
||||||
|
following it with "(X more messages)" where X is how many more chunks
|
||||||
|
there are. To get to these chunks, use the more command. One way to
|
||||||
|
try is to look at the default value of
|
||||||
|
supybot.replies.genericNoCapability -- it's so long that it'll
|
||||||
|
stretch across two messages.
|
||||||
|
|
||||||
|
<jemfinch|lambda> $config default
|
||||||
|
supybot.replies.genericNoCapability
|
||||||
|
<lambdaman> jemfinch|lambda: You're missing some capability
|
||||||
|
you need. This could be because you actually
|
||||||
|
possess the anti-capability for the capability
|
||||||
|
that's required of you, or because the channel
|
||||||
|
provides that anti-capability by default, or
|
||||||
|
because the global capabilities include that
|
||||||
|
anti-capability. Or, it could be because the
|
||||||
|
channel or the global defaultAllow is set to
|
||||||
|
False, meaning (1 more message)
|
||||||
|
<jemfinch|lambda> $more
|
||||||
|
<lambdaman> jemfinch|lambda: that no commands are allowed
|
||||||
|
unless explicitly in your capabilities. Either
|
||||||
|
way, you can't do what you want to do.
|
||||||
|
|
||||||
|
You should now have a solid foundation for using Supybot. Be sure to
|
||||||
|
check the help that is built-in to the bot itself if you have any
|
||||||
|
questions, and enjoy using Supybot!
|
||||||
48
docs/HACKING
Normal file
48
docs/HACKING
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
So, you want to hack on Supybot? Cool! I'm glad -- more developers
|
||||||
|
means more users, and more users means better software (although I
|
||||||
|
suppose more developers means better software even without the
|
||||||
|
addition of more users :))
|
||||||
|
|
||||||
|
Anyway, there are a few things you should know before you submit your
|
||||||
|
code to be accepted into Supybot. The first, and most important
|
||||||
|
thing is that we really do value your contribution. We may say that
|
||||||
|
it's not appropriate for the core distribution and any number of
|
||||||
|
varying reasons, but regardless, we're happy that you're hacking on
|
||||||
|
Supybot and bending it to your will, and we'll be happy to post your
|
||||||
|
patch as long as it applies cleanly.
|
||||||
|
|
||||||
|
The second thing you should know is that, despite the fact that we're
|
||||||
|
happy you want to contribute to Supybot, we're not afraid to piss you
|
||||||
|
off by turning down your code. We won't hesitate to reject code
|
||||||
|
because it's "bad" or because it doesn't fit our style guidelines
|
||||||
|
(read docs/STYLE). We don't really care if it makes you angry or
|
||||||
|
makes you use another IRC bot; we're in the practice of writing good
|
||||||
|
software, not placating whiners. Despite this, we're not entirely
|
||||||
|
heartless, and if you've done something we're interested in, we're
|
||||||
|
willing to work with you and your code until such a time as it's
|
||||||
|
ready to be accepted into the core. But if, at some point, we say,
|
||||||
|
"This needs fixed" and you say, "I refuse to fix it," you can go put
|
||||||
|
your code on the patch tracker; our time together is done. Supybot
|
||||||
|
is #1 here -- we don't care about your feelings, we don't care about
|
||||||
|
jamessan's feelings, we don't care about jemfinch's feelings if it
|
||||||
|
means that the code quality and user experience of Supybot is to
|
||||||
|
suffer.
|
||||||
|
|
||||||
|
Anyway, the normal process is that you'll submit a few patches,
|
||||||
|
jemfinch will review them and tell you what needs to happen for them
|
||||||
|
to be accepted into the core, you'll fix those problems, jemfinch
|
||||||
|
will review them again, that cycle will repeat a few times. When
|
||||||
|
your code is to jemfinch's satisfaction, it'll be integrated into the
|
||||||
|
core. For many people, this is the end of the line. For some
|
||||||
|
others (perhaps you!), you'll continue to write patches for Supybot,
|
||||||
|
and your coding ability and commitment will be obvious through
|
||||||
|
those. If your code quality is consistently high enough that
|
||||||
|
jemfinch (or other Supybot developers) don't have to spend a
|
||||||
|
significant amount of time reviewing your code, you'll be added as a
|
||||||
|
developer on the SF.net project and given commit access to our CVS
|
||||||
|
repository. From then on, you can do what you want, but be aware
|
||||||
|
that the other developers are watching what you do -- if you have a
|
||||||
|
big architecture change, you should probably talk to them before you
|
||||||
|
commit.
|
||||||
|
|
||||||
|
So welcome aboard, and have fun hacking on Supybot!
|
||||||
271
docs/INTERFACES
Normal file
271
docs/INTERFACES
Normal file
@ -0,0 +1,271 @@
|
|||||||
|
These are the interfaces for some of the objects you'll deal with if
|
||||||
|
you code for Supybot.
|
||||||
|
|
||||||
|
ircmsgs.IrcMsg:
|
||||||
|
This is the object that represents an IRC message. It has
|
||||||
|
several methods and attributes. The most important thing
|
||||||
|
about this class, however, is that it *is* hashable, and thus
|
||||||
|
*cannot* be modified. Do not change any attributes; any code
|
||||||
|
that modifies an IRC message is *broken* and should not
|
||||||
|
exist.
|
||||||
|
|
||||||
|
Interesting Methods:
|
||||||
|
__init__: One of the more complex initializers in
|
||||||
|
a class. It can be used in three different ways:
|
||||||
|
|
||||||
|
1) It can be given a string, as one received from
|
||||||
|
the server, which it will then parse into its
|
||||||
|
separate components and instantiate the class
|
||||||
|
with those components as attributes.
|
||||||
|
|
||||||
|
2) It can be given a command, some (optional)
|
||||||
|
arguments, and a (optional) prefix, and will
|
||||||
|
instantiate the class with those components as
|
||||||
|
attributes.
|
||||||
|
|
||||||
|
3) It can be given, in addition to any of the
|
||||||
|
above arguments, a 'msg' keyword argument that
|
||||||
|
will use the attributes of msg as defaults.
|
||||||
|
This exists to make it easier to copy
|
||||||
|
messages, since the class is immutable.
|
||||||
|
|
||||||
|
__str__: This returns the message in a string form
|
||||||
|
suitable for sending to a server.
|
||||||
|
|
||||||
|
__repr__: This returns the message in a form
|
||||||
|
suitable for eval(), assuming the name "IrcMsg" is
|
||||||
|
in your namespace and is bound to this class.
|
||||||
|
|
||||||
|
Interesting Attributes:
|
||||||
|
This is the meat of this class. These are
|
||||||
|
generally what you'll be looking at with IrcMsgs.
|
||||||
|
|
||||||
|
command: This is the command of the IrcMsg --
|
||||||
|
PRIVMSG, NOTICE, WHOIS, etc.
|
||||||
|
|
||||||
|
args: This is a tuple of the arguments to the
|
||||||
|
IrcMsg. Some messages have arguments, some don't,
|
||||||
|
depending on what command they are. You are, of
|
||||||
|
course, always assured that args exists and is a
|
||||||
|
tuple, though it might be empty.
|
||||||
|
|
||||||
|
prefix: This is the hostmask of the person/server
|
||||||
|
the message is from. In general, you won't be
|
||||||
|
setting this on your outgoing messages, but
|
||||||
|
incoming messages will always have one. This is
|
||||||
|
the whole hostmask; if the message was received
|
||||||
|
from a server, it'll be the server's hostmask; if
|
||||||
|
the message was received from a user, it'll be the
|
||||||
|
whole user hostmask. In that case, however, it's
|
||||||
|
also parsed out into the nick/user/host
|
||||||
|
attributes, which are probably more useful to
|
||||||
|
check for many purposes.
|
||||||
|
|
||||||
|
nick: If the message was sent by a user, this will
|
||||||
|
be the nick of the user. If it was sent by a
|
||||||
|
server, this will be the server's name (something
|
||||||
|
like calvino.freenode.net or similar).
|
||||||
|
|
||||||
|
user: If the message was sent by a user, this will
|
||||||
|
be the user string of the user -- what they put
|
||||||
|
into their IRC client for their "full name." If
|
||||||
|
it was sent by a server, it'll be the server's
|
||||||
|
name, again.
|
||||||
|
|
||||||
|
host: If the message was sent by a user, this will
|
||||||
|
be the host portion of their hostmask. If it was
|
||||||
|
sent by a server, it'll be the server's name (yet
|
||||||
|
again :))
|
||||||
|
|
||||||
|
|
||||||
|
irclib.Irc:
|
||||||
|
This is the object to handle everything about IRC except the
|
||||||
|
actual connection to the server itself. (*NOTE* that the
|
||||||
|
object actually received by commands in subclasses of
|
||||||
|
callbacks.Privmsg is an IrcObjectProxy, which is described
|
||||||
|
later. It augments the following interface with several
|
||||||
|
methods of its own to help plugin authors.)
|
||||||
|
|
||||||
|
Interesting Methods:
|
||||||
|
The two following messages (queueMsg and
|
||||||
|
sendMsg) are the methods by far most commonly
|
||||||
|
called by plugin authors. They're generally
|
||||||
|
the only methods you need to pay attention to
|
||||||
|
if you're writing plugins.
|
||||||
|
|
||||||
|
queueMsg: Queues a message for sending to the
|
||||||
|
server. The queue is generally FIFO, but it
|
||||||
|
does prioritize messages based on their command.
|
||||||
|
|
||||||
|
sendMsg: Queues a message for sending to the
|
||||||
|
server prior to any messages in the normal
|
||||||
|
queue. This is exactly a FIFO queue, no
|
||||||
|
reordering is done at all.
|
||||||
|
|
||||||
|
The following two methods are the most important
|
||||||
|
for people writing new IrcDrivers. Otherwise,
|
||||||
|
you really don't need to pay attention to them.
|
||||||
|
|
||||||
|
feedMsg: Feeds the Irc object a message for it
|
||||||
|
handle appropriately, as well as passing it on
|
||||||
|
to callbacks.
|
||||||
|
|
||||||
|
takeMsg: If the Irc object has a message it's
|
||||||
|
ready to send to the server, this will return
|
||||||
|
it. Otherwise, it will return None.
|
||||||
|
|
||||||
|
The next several methods are of far more marginal
|
||||||
|
utility. But someone may need them, so they're
|
||||||
|
documented here.
|
||||||
|
|
||||||
|
addCallback: Takes a callback to add to the list
|
||||||
|
of callbacks in the Irc object. See the
|
||||||
|
interface for IrcCallback for more information.
|
||||||
|
|
||||||
|
getCallback: Gets a callback by name, if it is
|
||||||
|
in the Irc object's list of callbacks. If it
|
||||||
|
it isn't, returns None.
|
||||||
|
|
||||||
|
removeCallback: Removes a callback by name.
|
||||||
|
Returns a list of the callbacks removed (since
|
||||||
|
it is technically possible to have multiple
|
||||||
|
callbacks with the same name. This list may
|
||||||
|
be empty.
|
||||||
|
|
||||||
|
__init__: Requires a nick. Optional arguments
|
||||||
|
include user and ident, which default to the
|
||||||
|
nick given, password, which defaults to the empty
|
||||||
|
password, and callbacks, a list of callbacks
|
||||||
|
(which defaults to nothing, an empty list).
|
||||||
|
|
||||||
|
reset: Resets the Irc object to its original
|
||||||
|
state, as well as sends a reset() to every
|
||||||
|
callbacks.
|
||||||
|
|
||||||
|
die: Kills the IRC object and all its callbacks.
|
||||||
|
|
||||||
|
Interesting attributes:
|
||||||
|
nick: The current nick of the bot.
|
||||||
|
|
||||||
|
prefix: The current prefix of the bot.
|
||||||
|
|
||||||
|
server: The current server the bot is connected to.
|
||||||
|
|
||||||
|
network: The current network name the bot is connected to.
|
||||||
|
|
||||||
|
afterConnect: False until the bot has received a
|
||||||
|
command sent after the connection is finished --
|
||||||
|
376, 377, or 422.
|
||||||
|
|
||||||
|
state: An IrcState object for this particular
|
||||||
|
connection. See the interface for the IrcState
|
||||||
|
object for more information.
|
||||||
|
|
||||||
|
|
||||||
|
irclib.IrcCallback:
|
||||||
|
Interesting Methods:
|
||||||
|
name: Returns the name of the callback. The
|
||||||
|
default implementation simply returns the name
|
||||||
|
of the class.
|
||||||
|
|
||||||
|
__call__: Called by the Irc object with itself
|
||||||
|
and the message whenever a message is fed to
|
||||||
|
the Irc object. Nothing is done with the return
|
||||||
|
value.
|
||||||
|
|
||||||
|
inFilter: Called by the Irc object with itself
|
||||||
|
and the message whenever a message is fed to
|
||||||
|
the Irc object. The return value should be an
|
||||||
|
IrcMsg object to be passed to the next callback
|
||||||
|
in the Irc's list of callbacks. If None is
|
||||||
|
returned, all processing stops. This gives
|
||||||
|
callbacks an oppurtunity to "filter" incoming
|
||||||
|
messages before general callbacks are given
|
||||||
|
them.
|
||||||
|
|
||||||
|
outFilter: Basically equivalent to inFilter,
|
||||||
|
except instead of being called on messages
|
||||||
|
as they enter the Irc object, it's called on
|
||||||
|
messages as they leave the Irc object.
|
||||||
|
|
||||||
|
die: Called when the parent Irc is told to
|
||||||
|
die. This gives callbacks an oppurtunity to
|
||||||
|
close open files, network connections, or
|
||||||
|
databases before they're deleted.
|
||||||
|
|
||||||
|
reset: Called when the parent Irc is told to
|
||||||
|
reset (which is generally when reconnecting
|
||||||
|
to the server). Most callbacks don't need
|
||||||
|
to define this.
|
||||||
|
|
||||||
|
Interesting attributes:
|
||||||
|
priority: Determines the priority of the
|
||||||
|
callback in the Irc object's list of
|
||||||
|
callbacks. Defaults to 99; the valid range
|
||||||
|
includes 0 through sys.maxint-1 (don't use
|
||||||
|
sys.maxint itself, that's reserved for the
|
||||||
|
Misc plugin). The lower the number, the
|
||||||
|
higher the priority. High priority
|
||||||
|
callbacks are called earlier in the
|
||||||
|
inFilter cycle, earlier in the __call__
|
||||||
|
cycle, and later in the outFilter cycle --
|
||||||
|
basically, they're given the first chances
|
||||||
|
on the way in and the last chances on the
|
||||||
|
way out.
|
||||||
|
|
||||||
|
|
||||||
|
callbacks.IrcObjectProxy:
|
||||||
|
IrcObjectProxy is a proxy for an irclib.Irc instance that
|
||||||
|
serves to provide a much fuller interface for handling
|
||||||
|
replies and errors as well as to handle the nesting of
|
||||||
|
commands. This is what you'll be dealing with almost all the
|
||||||
|
time when writing commands; when writing doCommand methods
|
||||||
|
(the kind you read about in the interface description of
|
||||||
|
irclib.IrcCallback) you'll be dealing with plain old
|
||||||
|
irclib.Irc objects.
|
||||||
|
|
||||||
|
Interesting methods:
|
||||||
|
reply: Called to reply to the current message
|
||||||
|
with a string that is to be the reply.
|
||||||
|
|
||||||
|
replySuccess, replyError: These reply with the
|
||||||
|
configured responses for success and generic
|
||||||
|
error, respectively. If an additional argument
|
||||||
|
is given, it's (intelligently) appended to the
|
||||||
|
generic message to be more specific.
|
||||||
|
|
||||||
|
error: Called to send an error reply to the
|
||||||
|
current message; not only does the response
|
||||||
|
indicate an error, but commands that error out
|
||||||
|
break the nested-command chain, which is
|
||||||
|
generally useful for not confusing the user :)
|
||||||
|
|
||||||
|
errorNoCapability: Like error, except it accepts
|
||||||
|
the capability that's missing and integrates it
|
||||||
|
into the configured error message for such
|
||||||
|
things. Also accepts an additional string for a
|
||||||
|
more descriptive message, if that's what you
|
||||||
|
want.
|
||||||
|
|
||||||
|
errorPossibleBug, errorNotRegistered,
|
||||||
|
errorNoUser, errorRequiresPrivacy: These methods
|
||||||
|
reply with the appropriate configured error
|
||||||
|
message for the conditions in their names; they
|
||||||
|
all take an additional arguments to be more
|
||||||
|
specific about the conditions they indicate, but
|
||||||
|
this argument is very rarely necessary.
|
||||||
|
|
||||||
|
getRealIrc: Returns the actual Irc object being
|
||||||
|
proxied for.
|
||||||
|
|
||||||
|
replies: Sends a collection of messages to a given
|
||||||
|
target, much like reply; except in this case, the user
|
||||||
|
can configure whether the messages will be sent
|
||||||
|
one-by-one or combined into a single message. Thus, the
|
||||||
|
method accepts a "prefixer" argument, which prefixes the
|
||||||
|
messages with a given string (or according to a given
|
||||||
|
function), a "joiner" string (or function) used to join
|
||||||
|
the messages into a single message if necessary, and an
|
||||||
|
onlyPrefixFirst argument which determines whether only
|
||||||
|
the first message will be prefixed when the messages are
|
||||||
|
sent separately (it defaults to False).
|
||||||
61
docs/OVERVIEW
Normal file
61
docs/OVERVIEW
Normal file
@ -0,0 +1,61 @@
|
|||||||
|
So here's a general *programming* introduction to what the different
|
||||||
|
modules do and what services they provide. It is, however, only an
|
||||||
|
introduction. Read the modules themselves for a much more detailed
|
||||||
|
explanation :)
|
||||||
|
|
||||||
|
fix.py: Stuff that Python should (but doesn't) include by default.
|
||||||
|
|
||||||
|
cdb.py: A constant database library, translated from C (and my O'Caml
|
||||||
|
version) More information available at
|
||||||
|
http://cr.yp.to/cdb.html. Not currently used since we
|
||||||
|
switched to PySQLite.
|
||||||
|
|
||||||
|
ansi.py: Contains different ANSI color sequences.
|
||||||
|
Mostly used by the debug module.
|
||||||
|
|
||||||
|
conf.py: The configuration file for the bot -- it sets a lot of
|
||||||
|
variables that other modules check for when they have
|
||||||
|
questions about what they need to do.
|
||||||
|
|
||||||
|
world.py: Just a dropping off place for some globals that need to be
|
||||||
|
shared among all the modules. It's obviously not used *a
|
||||||
|
lot*, but some things seem to fit better here than anywhere
|
||||||
|
else.
|
||||||
|
|
||||||
|
privmsgs.py: Basic stuff relating to callbacks.Privmsg, the base class
|
||||||
|
for most plugins.
|
||||||
|
|
||||||
|
callbacks.py: A few basic callbacks providing significant
|
||||||
|
functionality. You'll likely be inheriting from Privmsg
|
||||||
|
quite a bit.
|
||||||
|
|
||||||
|
ircdb.py: The users and channels databases are here, as well as the
|
||||||
|
IrcUser and IrcChannel classes. Look here when you want to
|
||||||
|
restrict a command to only certain users.
|
||||||
|
|
||||||
|
irclib.py: Provides the most important class in the irclib, Irc. It
|
||||||
|
represents a connection to an IRC server, but it's entirely
|
||||||
|
separate from the network implementation. It's connected
|
||||||
|
to the network (or whatever else drives it) by a "driver"
|
||||||
|
module which uses its feedMsg/takeMsg functions.
|
||||||
|
|
||||||
|
drivers.py: The baseclass (IrcDriver) for various drivers to drive
|
||||||
|
irclib.Irc classes. Also, the driving mechanism.
|
||||||
|
|
||||||
|
asyncoreDrivers.py: The asyncore-based drivers for use with the bot.
|
||||||
|
|
||||||
|
socketDrivers.py: The plain old socket-based drivers for use with the
|
||||||
|
bot.
|
||||||
|
|
||||||
|
twistedDrivers.py: The Twisted <http://www.twistedmatrix.com/> drivers
|
||||||
|
for use with the bot.
|
||||||
|
|
||||||
|
ircmsgs.py: The IrcMsg class (get to know it :)) and various functions
|
||||||
|
for making the creation of IrcMsgs easier.
|
||||||
|
|
||||||
|
ircutils.py: Various utility functions for Irc -- read the module to
|
||||||
|
see what goodies are there :)
|
||||||
|
|
||||||
|
schedule.py: A schedule driver (which is automatically registered with
|
||||||
|
the drivers module) to run things at a particular time,
|
||||||
|
or at specified periods of time.
|
||||||
449
docs/PLUGIN-EXAMPLE
Normal file
449
docs/PLUGIN-EXAMPLE
Normal file
@ -0,0 +1,449 @@
|
|||||||
|
*******************************************************************************
|
||||||
|
The plugins/Random.py included with the distribution has been
|
||||||
|
updated to use an argument-parsing module recently added to Supybot
|
||||||
|
but not yet documented. Still, all of the functions used in this
|
||||||
|
tutorial are available, so the code (as shown in this tutorial*
|
||||||
|
should still work.
|
||||||
|
*******************************************************************************
|
||||||
|
|
||||||
|
Ok, so you want to write a callback for Supybot. Good, then this is
|
||||||
|
the place to be. We're going to start from the top (the highest
|
||||||
|
level, where Supybot code does the most work for you) and move lower
|
||||||
|
after that.
|
||||||
|
|
||||||
|
So have you used Supybot? If not, you need to go use it, get a feel
|
||||||
|
for it, see how the various commands work and such.
|
||||||
|
|
||||||
|
So now that we know you've used Supybot, we'll start getting into
|
||||||
|
details.
|
||||||
|
|
||||||
|
First, the easiest way to start writing a module is to use the wizard
|
||||||
|
provided, scripts/newplugin.py. Here's an example session:
|
||||||
|
|
||||||
|
-----
|
||||||
|
functor% supybot-newplugin
|
||||||
|
What should the name of the plugin be? Random
|
||||||
|
Supybot offers two major types of plugins: command-based and regexp-
|
||||||
|
based. Command-based plugins are the kind of plugins you've seen most
|
||||||
|
when you've used supybot. They're also the most featureful and
|
||||||
|
easiest to write. Commands can be nested, for instance, whereas
|
||||||
|
regexp-based callbacks can't do nesting. That doesn't mean that
|
||||||
|
you'll never want regexp-based callbacks. They offer a flexibility
|
||||||
|
that command-based callbacks don't offer; however, they don't tie into
|
||||||
|
the whole system as well. If you need to combine a command-based
|
||||||
|
callback with some regexp-based methods, you can do so by subclassing
|
||||||
|
callbacks.PrivmsgCommandAndRegexp and then adding a class-level
|
||||||
|
attribute "regexps" that is a sets.Set of methods that are regexp-
|
||||||
|
based. But you'll have to do that yourself after this wizard is
|
||||||
|
finished :)
|
||||||
|
Do you want a command-based plugin or a regexp-based plugin? [command/
|
||||||
|
regexp] command
|
||||||
|
Sometimes you'll want a callback to be threaded. If its methods
|
||||||
|
(command or regexp-based, either one) will take a signficant amount
|
||||||
|
of time to run, you'll want to thread them so they don't block
|
||||||
|
the entire bot.
|
||||||
|
|
||||||
|
Does your plugin need to be threaded? [y/n] n
|
||||||
|
Your new plugin template is Random.py
|
||||||
|
functor%
|
||||||
|
-----
|
||||||
|
|
||||||
|
So that's what it looks like. Now let's look at the source code (if
|
||||||
|
you'd like to look at it in your programming editor, the whole plugin
|
||||||
|
is available as examples/Random.py):
|
||||||
|
|
||||||
|
-----
|
||||||
|
#!/usr/bin/env python
|
||||||
|
|
||||||
|
###
|
||||||
|
# Copyright (c) 2004, Jeremiah Fincher
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
#
|
||||||
|
# * Redistributions of source code must retain the above copyright notice,
|
||||||
|
# this list of conditions, and the following disclaimer.
|
||||||
|
# * Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions, and the following disclaimer in the
|
||||||
|
# documentation and/or other materials provided with the distribution.
|
||||||
|
# * Neither the name of the author of this software nor the name of
|
||||||
|
# contributors to this software may be used to endorse or promote products
|
||||||
|
# derived from this software without specific prior written consent.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
||||||
|
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||||
|
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||||
|
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||||
|
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||||
|
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||||
|
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||||
|
# POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
###
|
||||||
|
|
||||||
|
"""
|
||||||
|
Add the module docstring here. This will be used by the setup.py script.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__revision__ = "$Id$"
|
||||||
|
__author__ = ''
|
||||||
|
|
||||||
|
import supybot.plugins as plugins
|
||||||
|
|
||||||
|
import supybot.conf as conf
|
||||||
|
import supybot.utils as utils
|
||||||
|
import supybot.privmsgs as privmsgs
|
||||||
|
import supybot.callbacks as callbacks
|
||||||
|
|
||||||
|
|
||||||
|
def configure(advanced):
|
||||||
|
# This will be called by setup.py to configure this module. Advanced is
|
||||||
|
# a bool that specifies whether the user identified himself as an advanced
|
||||||
|
# user or not. You should effect your configuration by manipulating the
|
||||||
|
# registry as appropriate.
|
||||||
|
from questions import expect, anything, something, yn
|
||||||
|
conf.registerPlugin('Random', True)
|
||||||
|
|
||||||
|
class Random(callbacks.Privmsg):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
Class = Random
|
||||||
|
|
||||||
|
# vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78:
|
||||||
|
-----
|
||||||
|
|
||||||
|
So a few notes, before we customize it.
|
||||||
|
|
||||||
|
You'll probably want to change the copyright notice to be your name.
|
||||||
|
It wouldn't stick even if you kept my name, so you might as well :)
|
||||||
|
|
||||||
|
Describe what you want the plugin to do in the docstring. This is
|
||||||
|
used in supybot-wizard in order to explain to the user the purpose of
|
||||||
|
the module. It's also returned when someone asks the bot for help for
|
||||||
|
a given module (instead of help for a certain command). We'll change
|
||||||
|
this one to "Lots of stuff relating to random numbers."
|
||||||
|
|
||||||
|
Then there are the imports. The callbacks module is used (the class
|
||||||
|
you're given subclasses callbacks.Privmsg) but the privmsgs module
|
||||||
|
isn't used. That's alright; we can almost guarantee you'll use it, so
|
||||||
|
we go ahead and add the import to the template.
|
||||||
|
|
||||||
|
Then you see a "configure" function. This is the function that's
|
||||||
|
called when users decide to add your module in supybot-wizard. You'll
|
||||||
|
note that by default it simply registers the plugin to be
|
||||||
|
automatically loaded on startup. For many plugins this is all you
|
||||||
|
need; for more complex plugins, you might need to ask questions and
|
||||||
|
add commands based on the answers.
|
||||||
|
|
||||||
|
Now comes the meat of the plugin: the plugin class.
|
||||||
|
|
||||||
|
What you're given is a skeleton: a simple subclass of
|
||||||
|
callbacks.Privmsg for you to start with. Now let's add a command.
|
||||||
|
|
||||||
|
I don't know what you know about random number generators, but the
|
||||||
|
short of it is that they start at a certain number (a seed) and they
|
||||||
|
continue (via some somewhat complicated/unpredictable algorithm) from
|
||||||
|
there. This seed (and the rest of the sequence, really) is all nice
|
||||||
|
and packaged up in Python's random module, the Random object. So the
|
||||||
|
first thing we're going to have to do is give our plugin a Random
|
||||||
|
object.
|
||||||
|
|
||||||
|
Normally, when we want to give instances of a class an object, we'll
|
||||||
|
do so in the __init__ method. And that works great for plugins, too.
|
||||||
|
The one thing you have to be careful of is that you call the
|
||||||
|
superclass __init__ method at the end of your own __init__. So to add
|
||||||
|
this random.Random object to our plugin, we can replace the "pass"
|
||||||
|
statement with this:
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
self.rng = random.Random()
|
||||||
|
callbacks.Privmsg.__init__(self)
|
||||||
|
|
||||||
|
(rng is an abbreviation for "random number generator," in case you
|
||||||
|
were curious)
|
||||||
|
|
||||||
|
Do be careful not to give your __init__ any arguments (other than
|
||||||
|
self, of course). There's no way anything will ever get to them! If
|
||||||
|
you have some sort of initial values you need to get to your plugin
|
||||||
|
before it can do anything interesting, you should get those values
|
||||||
|
from the registry.
|
||||||
|
|
||||||
|
There's an easier way to get our plugin to have its own rng than to
|
||||||
|
define an __init__. Plugins are unique among classes because we're
|
||||||
|
always certain that there will only be one instance -- supybot doesn't
|
||||||
|
allow us to load multiple instances of a single plugin. So instead of
|
||||||
|
adding the rng in __init__, we can just add it as a attribute to the
|
||||||
|
class itself. Like so (replacing the "pass" statement again):
|
||||||
|
|
||||||
|
rng = random.Random()
|
||||||
|
|
||||||
|
And we save two lines of code and make our code a little more clear :)
|
||||||
|
|
||||||
|
Now that we have an RNG, we need some way to get random numbers. So
|
||||||
|
first, we'll add a command that simply gets the next random number and
|
||||||
|
gives it back to the user. It takes no arguments, of course (what
|
||||||
|
would you give it?). Here's the command, and I'll follow that with
|
||||||
|
the explanation of what each part means.
|
||||||
|
|
||||||
|
def random(self, irc, msg, args):
|
||||||
|
"""takes no arguments
|
||||||
|
|
||||||
|
Returns the next random number generated by the random number
|
||||||
|
generator.
|
||||||
|
"""
|
||||||
|
irc.reply(str(self.rng.random()))
|
||||||
|
|
||||||
|
And that's it! Pretty simple, huh? Anyway, you're probably wondering
|
||||||
|
what all that *means*. We'll start with the def statement:
|
||||||
|
|
||||||
|
def random(self, irc, msg, args):
|
||||||
|
|
||||||
|
What that does is define a command "random". You can call it by
|
||||||
|
saying "@random" (or whatever prefix character your specific bot
|
||||||
|
uses). The arguments are a bit less obvious. Self is self-evident
|
||||||
|
(hah!). irc is the Irc object passed to the command; msg is the
|
||||||
|
original IrcMsg object. But you're really not going to have to deal
|
||||||
|
with either of these too much (with the exception of calling irc.reply
|
||||||
|
or irc.error). What you're *really* interested in is the args arg.
|
||||||
|
That is a list of all the arguments passed to your command, pre-parsed
|
||||||
|
and already evaluated (i.e., you never have to worry about nested
|
||||||
|
commands, or handling double quoted strings, or splitting on
|
||||||
|
whitespace -- the work has already been done for you). You can read
|
||||||
|
about the Irc object in irclib.py (you won't find .reply or .error
|
||||||
|
there, though, because you're actually getting an IrcObjectProxy, but
|
||||||
|
that's beyond the level we want to describe here :)). You can read
|
||||||
|
about the msg object in ircmsgs.py. But again, you'll very rarely be
|
||||||
|
using these objects.
|
||||||
|
|
||||||
|
(In case you're curious, the answer is yes, you *must* name your
|
||||||
|
arguments (self, irc, msg, args). The names of those arguments is one
|
||||||
|
of the ways that supybot uses to determine which methods in a plugin
|
||||||
|
class are commands and which aren't. And while we're talking about
|
||||||
|
naming restrictions, all your commands should be named in
|
||||||
|
all-lowercase with no underscores. Before calling a command, supybot
|
||||||
|
always converts the command name to lowercase and removes all dashes
|
||||||
|
and underscores. On the other hand, you now know an easy way to make
|
||||||
|
sure a method is never called (even if its arguments are (self, irc,
|
||||||
|
msg, args), however unlikely that may be). Just name it with an
|
||||||
|
underscore or an uppercase letter in it :))
|
||||||
|
|
||||||
|
You'll also note that the docstring is odd. The wonderful thing about
|
||||||
|
the supybot framework is that it's easy to write complete commands
|
||||||
|
with help and everything: the docstring *IS* the help! Given the
|
||||||
|
above docstring, this is what a supybot does:
|
||||||
|
|
||||||
|
<jemfinch> @help random
|
||||||
|
<angryman> jemfinch: (random takes no arguments) -- Returns the
|
||||||
|
next random number from the random number generator.
|
||||||
|
|
||||||
|
Now on to the actual body of the function:
|
||||||
|
|
||||||
|
irc.reply(str(self.rng.random()))
|
||||||
|
|
||||||
|
irc.reply takes one simple argument: a string. The string is the
|
||||||
|
reply to be sent. Don't worry about length restrictions or anything
|
||||||
|
-- if the string you want to send is too big for an IRC message (and
|
||||||
|
oftentimes that turns out to be the case :)) the Supybot framework
|
||||||
|
handles that entirely transparently to you. Do make sure, however,
|
||||||
|
that you give irc.reply a string. It doesn't take anything else
|
||||||
|
(sometimes even unicode fails!). That's why we have
|
||||||
|
"str(self.rng.random())" instead of simply "self.rng.random()" -- we
|
||||||
|
had to give irc.reply a string.
|
||||||
|
|
||||||
|
Anyway, now that we have an RNG, we have a need for seed! Of course,
|
||||||
|
Python gives us a good seed already (it uses the current time as a
|
||||||
|
seed if we don't give it one) but users might want to be able to
|
||||||
|
repeat "random" sequences, so letting them set the seed is a good
|
||||||
|
thing. So we'll add a seed command to give the RNG a specific seed:
|
||||||
|
|
||||||
|
def seed(self, irc, msg, args):
|
||||||
|
"""<seed>
|
||||||
|
|
||||||
|
Sets the seed of the random number generator. <seed> must be
|
||||||
|
an int or a long.
|
||||||
|
"""
|
||||||
|
seed = privmsgs.getArgs(args)
|
||||||
|
try:
|
||||||
|
seed = long(seed)
|
||||||
|
except ValueError:
|
||||||
|
# It wasn't a valid long!
|
||||||
|
irc.error('<seed> must be a valid int or long.')
|
||||||
|
return
|
||||||
|
self.rng.seed(seed)
|
||||||
|
irc.replySuccess()
|
||||||
|
|
||||||
|
So this one's a bit more complicated. But it's still pretty simple.
|
||||||
|
The method name is "seed" so that'll be the command name. The
|
||||||
|
arguments are the same, the docstring is of the same form, so we don't
|
||||||
|
need to go over that again. The body of the function, however, is
|
||||||
|
significantly different.
|
||||||
|
|
||||||
|
privmsgs.getArgs is a function you're going to be seeing a lot of when
|
||||||
|
you write plugins for Supybot. What it does is basically give you the
|
||||||
|
right number of arguments for your comamnd. In this case, we want one
|
||||||
|
argument. But we might have been given any number of arguments by the
|
||||||
|
user. So privmsgs.getArgs joins them appropriately, leaving us with
|
||||||
|
one single "seed" argument (by default, it returns one argument as a
|
||||||
|
single value; more arguments are returned in a tuple/list). Yes, we
|
||||||
|
could've just said "seed = args[0]" and gotten the first argument, but
|
||||||
|
what if the user didn't pass us an argument at all? Then we've got to
|
||||||
|
catch the IndexError from args[0] and complain to the user about it.
|
||||||
|
privmsgs.getArgs, on the other hand, handles all that for us. If the
|
||||||
|
user didn't give us enough arguments, it'll reply with the help string
|
||||||
|
for the command, thus saving us the effort.
|
||||||
|
|
||||||
|
So we have the seed from privmsgs.getArgs. But it's a string. The
|
||||||
|
next three lines are pretty darn obvious: we're just converting the
|
||||||
|
string to a int of some sort. But if it's not, that's when we're
|
||||||
|
going to call irc.error. It has the same interface as we saw before
|
||||||
|
in irc.reply, but it makes sure to remind the user that an error has
|
||||||
|
been encountered (currently, that means it puts "Error: " at the
|
||||||
|
beginning of the message). After erroring, we return. It's important
|
||||||
|
to remember this return here; otherwise, we'll just keep going down
|
||||||
|
through the function and try to use this "seed" variable that never
|
||||||
|
got assigned. A good general rule of thumb is that any time you use
|
||||||
|
irc.error, you'll want to return immediately afterwards.
|
||||||
|
|
||||||
|
Then we set the seed -- that's a simple function on our rng object.
|
||||||
|
Assuming that succeeds (and doesn't raise an exception, which it
|
||||||
|
shouldn't, because we already read the documentation and know that it
|
||||||
|
should work) we reply to say that everything worked fine. That's what
|
||||||
|
irc.replySuccess says. By default, it has the very dry (and
|
||||||
|
appropriately robot-like) "The operation succeeded." but you're
|
||||||
|
perfectly welcome to customize it yourself -- the registry was written to
|
||||||
|
be modified!
|
||||||
|
|
||||||
|
So that's a bit more complicated command. But we still haven't dealt
|
||||||
|
with multiple arguments. Let's do that next.
|
||||||
|
|
||||||
|
So these random numbers are useful, but they're not the kind of random
|
||||||
|
numbers we usually want in Real Life. In Real Life, we like to tell
|
||||||
|
someone to "pick a number between 1 and 10." So let's write a
|
||||||
|
function that does that. Of course, we won't hardcode the 1 or the 10
|
||||||
|
into the function, but we'll take them as arguments. First the
|
||||||
|
function:
|
||||||
|
|
||||||
|
def range(self, irc, msg, args):
|
||||||
|
"""<start> <end>
|
||||||
|
|
||||||
|
Returns a number between <start> and <end>, inclusive (i.e., the number
|
||||||
|
can be either of the endpoints.
|
||||||
|
"""
|
||||||
|
(start, end) = privmsgs.getArgs(args, required=2)
|
||||||
|
try:
|
||||||
|
end = int(end)
|
||||||
|
start = int(start)
|
||||||
|
except ValueError:
|
||||||
|
irc.error('<start> and <end> must both be integers.')
|
||||||
|
return
|
||||||
|
# .randrange() doesn't include the endpoint, so we use end+1.
|
||||||
|
irc.reply(str(self.rng.randrange(start, end+1)))
|
||||||
|
|
||||||
|
Pretty simple. This is becoming old hat by now. The only new thing
|
||||||
|
here is the call to privmsgs.getArgs. We have to make sure, since we
|
||||||
|
want two values, to pass a keyword parameter "required" into
|
||||||
|
privmsgs.getArgs. Of course, privmsgs.getArgs handles all the
|
||||||
|
checking for missing arguments and whatnot so we don't have to.
|
||||||
|
|
||||||
|
The Random object we're using offers us a "sample" method that takes a
|
||||||
|
sequence and a number (we'll call it N) and returns a list of N items
|
||||||
|
taken randomly from the sequence. So I'll show you an example that
|
||||||
|
takes advantage of multiple arguments but doesn't use privmsgs.getArgs
|
||||||
|
(and thus has to handle its own errors if the number of arguments
|
||||||
|
isn't right). Here's the code:
|
||||||
|
|
||||||
|
def sample(self, irc, msg, args):
|
||||||
|
"""<number of items> [<text> ...]
|
||||||
|
|
||||||
|
Returns a sample of the <number of items> taken from the remaining
|
||||||
|
arguments. Obviously <number of items> must be less than the number
|
||||||
|
of arguments given.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
n = int(args.pop(0))
|
||||||
|
except IndexError: # raised by .pop(0)
|
||||||
|
raise callbacks.ArgumentError
|
||||||
|
except ValueError:
|
||||||
|
irc.error('<number of items> must be an integer.')
|
||||||
|
return
|
||||||
|
if n > len(args):
|
||||||
|
irc.error('<number of items> must be less than the number '
|
||||||
|
'of arguments.')
|
||||||
|
return
|
||||||
|
sample = self.rng.sample(args, n)
|
||||||
|
irc.reply(utils.commaAndify(map(repr, sample)))
|
||||||
|
|
||||||
|
Most everything here is familiar. The difference between this and the
|
||||||
|
previous examples is that we're dealing with args directly, rather
|
||||||
|
than through getArgs. Since we already have the arguments in a list,
|
||||||
|
it doesn't make any sense to have privmsgs.getArgs smush them all
|
||||||
|
together into a big long string that we'll just have to re-split. But
|
||||||
|
we still want the nice error handling of privmsgs.getArgs. So what do
|
||||||
|
we do? We raise callbacks.ArgumentError! That's the secret juju that
|
||||||
|
privmsgs.getArgs is doing; now we're just doing it ourself. Someone
|
||||||
|
up our callchain knows how to handle it so a neat error message is
|
||||||
|
returned. So in this function, if .pop(0) fails, we weren't given
|
||||||
|
enough arguments and thus need to tell the user how to call us.
|
||||||
|
|
||||||
|
So we have the args, we have the number, we do a simple call to
|
||||||
|
random.sample and then we do this funky utils.commaAndify to it.
|
||||||
|
Yeah, so I was running low on useful names :) Anyway, what it does is
|
||||||
|
take a list of strings and return a string with them joined by a
|
||||||
|
comma, the last one being joined with a comma and "and". So the list
|
||||||
|
['foo', 'bar', 'baz'] becomes "foo, bar, and baz". It's pretty useful
|
||||||
|
for showing the user lists in a useful form. We map the strings with
|
||||||
|
repr() first just to surround them with quotes.
|
||||||
|
|
||||||
|
So we have one more example. Yes, I hear your groans, but it's
|
||||||
|
pedagogically useful :) This time we're going to write a command that
|
||||||
|
makes the bot roll a die. It'll take one argument (the number of
|
||||||
|
sides on the die) and will respond with the equivalent of "/me rolls a
|
||||||
|
__" where __ is the number the bot rolled. So here's the code:
|
||||||
|
|
||||||
|
def diceroll(self, irc, msg, args):
|
||||||
|
"""[<number of sides>]
|
||||||
|
|
||||||
|
Rolls a die with <number of sides> sides. The default number
|
||||||
|
of sides is 6.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
n = privmsgs.getArgs(args, required=0, optional=1)
|
||||||
|
if not n:
|
||||||
|
n = 6
|
||||||
|
n = int(n)
|
||||||
|
except ValueError:
|
||||||
|
irc.error('Dice have integer numbers of sides. Use one.')
|
||||||
|
return
|
||||||
|
s = 'rolls a %s' % self.rng.randrange(1, n+1)
|
||||||
|
irc.reply(s, action=True)
|
||||||
|
|
||||||
|
There's a lot of stuff you haven't seen before in there. The most
|
||||||
|
important, though, is the first thing you'll notice that's different:
|
||||||
|
the privmsg.getArgs call. Here we're offering a default argument in
|
||||||
|
case the user is too lazy to supply one (or just wants a nice,
|
||||||
|
standard six-sided die :)) privmsgs.getArgs supports that; we'll just
|
||||||
|
tell it that we don't *need* any arguments (via required=0) and that
|
||||||
|
we *might like* one argument (optional=1). If the user provides an
|
||||||
|
argument, we'll get it -- if they don't, we'll just get an empty
|
||||||
|
string. Hence the "if not n: n = 6", where we provide the default.
|
||||||
|
|
||||||
|
You'll also note that irc.reply was given a keyword argument here,
|
||||||
|
"action". This means that the reply is to be made as an action rather
|
||||||
|
than a normal reply.
|
||||||
|
|
||||||
|
So that's our plugin. 5 commands, each building in complexity. You
|
||||||
|
should now be able to write most anything you want to do in Supybot.
|
||||||
|
Except regexp-based plugins, but that's a story for another day (and
|
||||||
|
those aren't nearly as cool as these command-based callbacks anyway
|
||||||
|
:)). Now we need to flesh it out to make it a full-fledged plugin.
|
||||||
|
|
||||||
|
TODO: Describe the registry and how to write a proper plugin configure
|
||||||
|
function.
|
||||||
|
|
||||||
|
We've written our own plugin from scratch (well, from the boilerplate
|
||||||
|
that we got from scripts/newplugin.py :)) and survived! Now go write
|
||||||
|
more plugins for supybot, and send them to me so I can use them too :)
|
||||||
188
docs/STYLE
Normal file
188
docs/STYLE
Normal file
@ -0,0 +1,188 @@
|
|||||||
|
====================================================================
|
||||||
|
Code not following these style guidelines fastidiously is likely
|
||||||
|
(*very* likely) not to be accepted into the Supybot core.
|
||||||
|
====================================================================
|
||||||
|
|
||||||
|
Read PEP 8 (Guido's Style Guide) and know that we use almost all the
|
||||||
|
same style guidelines.
|
||||||
|
|
||||||
|
Maximum line length is 79 characters. 78 is a safer bet, though.
|
||||||
|
This is **NON-NEGOTIABLE**. Your code will not be accepted while you
|
||||||
|
are violating this guidline.
|
||||||
|
|
||||||
|
Identation is 4 spaces per level. No tabs. This also is
|
||||||
|
**NON-NEGOTIABLE**. Your code, again, will *never* be accepted while
|
||||||
|
you have literal tabs in it.
|
||||||
|
|
||||||
|
Single quotes are used for all string literals that aren't docstrings.
|
||||||
|
They're just easier to type.
|
||||||
|
|
||||||
|
Triple double quotes (""") are always used for docstrings.
|
||||||
|
|
||||||
|
Raw strings (r'' or r"") should be used for regular expressions.
|
||||||
|
|
||||||
|
Spaces go around all operators (except around '=' in default
|
||||||
|
arguments to functions) and after all commas (unless doing so keeps a
|
||||||
|
line within the 79 character limit).
|
||||||
|
|
||||||
|
Functions calls should look like this: "foo(bar(baz(x), y))". They
|
||||||
|
should not look like "foo (bar (baz (x), y))", or like
|
||||||
|
"foo(bar(baz(x), y) )" or like anything else. I hate extraneous
|
||||||
|
spaces.
|
||||||
|
|
||||||
|
Class names are StudlyCaps. Method and function names are camelCaps
|
||||||
|
(StudlyCaps with an initial lowercase letter). If variable and
|
||||||
|
attribute names can maintain readability without being camelCaps,
|
||||||
|
then they should be entirely in lowercase, otherwise they should also
|
||||||
|
use camelCaps. Plugin names are StudlyCaps.
|
||||||
|
|
||||||
|
Imports should always happen at the top of the module, one import per
|
||||||
|
line (so if imports need to be added or removed later, it can be done
|
||||||
|
easily).
|
||||||
|
|
||||||
|
Unless absolutely required by some external force, imports should be
|
||||||
|
ordered by the string length of the module imported. I just think it
|
||||||
|
looks prettier.
|
||||||
|
|
||||||
|
A blank line should be between all consecutive method declarations in
|
||||||
|
a class definition. Two blank lines should be between all
|
||||||
|
consecutive class definitions in a file. Comments are even better
|
||||||
|
than blank lines for separating classes.
|
||||||
|
|
||||||
|
Database filenames should generally begin with the name of the plugin
|
||||||
|
and the extension should be 'db'. plugins.DBHandler does this
|
||||||
|
already.
|
||||||
|
|
||||||
|
Whenever creating a file descriptor or socket, keep a reference
|
||||||
|
around and be sure to close it. There should be no code like this:
|
||||||
|
s = urllib2.urlopen('url').read()
|
||||||
|
Instead, do this:
|
||||||
|
fd = urllib2.urlopen('url')
|
||||||
|
try:
|
||||||
|
s = fd.read()
|
||||||
|
finally:
|
||||||
|
fd.close()
|
||||||
|
This is to be sure the bot doesn't leak file descriptors.
|
||||||
|
|
||||||
|
All plugin files should include a docstring decsribing what the
|
||||||
|
plugin does. This docstring will be returned when the user is
|
||||||
|
configuring the plugin. All plugin classes should also include a
|
||||||
|
docstring describing how to do things with the plugin; this docstring
|
||||||
|
will be returned when the user requests help on a plugin name.
|
||||||
|
|
||||||
|
Method docstrings in classes deriving from callbacks.Privmsg should
|
||||||
|
include an argument list as their first line, and after that a blank
|
||||||
|
line followed by a longer description of what the command does. The
|
||||||
|
argument list is used by the 'syntax' command, and the longer
|
||||||
|
description is used by the 'help' command.
|
||||||
|
|
||||||
|
Whenever joining more than two strings, use string interpolation, not
|
||||||
|
addition:
|
||||||
|
s = x + y + z # Bad.
|
||||||
|
s = '%s%s%s' % (x, y, z) # Good.
|
||||||
|
s = ''.join([x, y, z]) # Best, but not as general.
|
||||||
|
This has to do with efficiency; the intermediate string x+y is made
|
||||||
|
(and thus copied) before x+y+z is made, so it's less efficient.
|
||||||
|
People who use string concatenation in a for loop will be swiftly
|
||||||
|
kicked in the head.
|
||||||
|
|
||||||
|
When writing strings that have formatting characters in them, don't
|
||||||
|
use anything but %s unless you absolutely must. In particular, %d
|
||||||
|
should never be used, it's less general than %s and serves no useful
|
||||||
|
purpose. If you got the %d wrong, you'll get an exception that says,
|
||||||
|
"foo instance can't be converted to an integer." But if you use %s,
|
||||||
|
you'll get to see your nice little foo instance, if it doesn't
|
||||||
|
convert to a string cleanly, and if it does convert cleanly, you'll
|
||||||
|
get to see what you expect to see. Basically, %d just sucks.
|
||||||
|
|
||||||
|
As a corrolary to the above, note that sometimes %f is used, but on
|
||||||
|
when floats need to be formatted, e.g., %.2f.
|
||||||
|
|
||||||
|
Use the log module to its fullest; when you need to print some values
|
||||||
|
to debug, use self.log.debug to do so, and leave those statements in
|
||||||
|
the code (commented out) so they can later be re-enabled. Remember
|
||||||
|
that once code is buggy, it tends to have more bugs, and you'll
|
||||||
|
probably need those print statements again.
|
||||||
|
|
||||||
|
While on the topic of logs, note that we do not use % (i.e.,
|
||||||
|
str.__mod__) with logged strings; we simple pass the format
|
||||||
|
parameters as additional arguments. The reason is simple: the
|
||||||
|
logging module supports it, and it's cleaner (fewer tokens/glyphs) to
|
||||||
|
read.
|
||||||
|
|
||||||
|
While still on the topic of logs, it's also important to pick the
|
||||||
|
appropriate log level for given information.
|
||||||
|
DEBUG: Appropriate to tell a programmer *how* we're doing
|
||||||
|
something (i.e., debugging printfs, basically). If
|
||||||
|
you're trying to figure out why your code doesn't work,
|
||||||
|
DEBUG is the new printf -- use that, and leave the
|
||||||
|
statements in your code.
|
||||||
|
INFO: Appropriate to tell a user *what* we're doing, when what
|
||||||
|
we're doing isn't important for the user to pay attention
|
||||||
|
to. A user who likes to keep up with things should enjoy
|
||||||
|
watching our logging at the INFO level; it shouldn't be
|
||||||
|
too low-level, but it should give enough information that
|
||||||
|
it keeps him relatively interested at peak times.
|
||||||
|
WARNING: Appropriate to tell a user when we're doing something
|
||||||
|
that he really ought to pay attention to. Users should
|
||||||
|
see WARNING and think, "Hmm, should I tell the Supybot
|
||||||
|
developers about this?" Later, he should decide not to,
|
||||||
|
but it should give the user a moment to pause and think
|
||||||
|
about what's actually happening with his bot.
|
||||||
|
ERROR: Appropriate to tell a user when something has gone wrong.
|
||||||
|
Uncaught exceptions are ERRORs. Conditions that we
|
||||||
|
absolutely want to hear about should be errors. Things
|
||||||
|
that should *scare* the user should be errors.
|
||||||
|
CRITICAL: Not really appropriate. I can think of no absolutely
|
||||||
|
critical issue yet encountered in Supybot; the only
|
||||||
|
possible thing I can imagine is to notify the user that
|
||||||
|
the partition on which Supybot is running has filled up.
|
||||||
|
That would be a CRITICAL condition, but it would also be
|
||||||
|
hard to log :)
|
||||||
|
|
||||||
|
All plugins should have test cases written for them. Even if it
|
||||||
|
doesn't actually test anything but just exists, it's good to have the
|
||||||
|
test there so there's a place to add more tests later (and so we can
|
||||||
|
be sure that all plugins are adequately documented; PluginTestCase
|
||||||
|
checks that every command has documentation)
|
||||||
|
|
||||||
|
All uses of eval() that expect to get integrated in Supybot must be
|
||||||
|
approved by jemfinch, no exceptions. Chances are, it won't be
|
||||||
|
accepted. Have you looked at utils.safeEval?
|
||||||
|
|
||||||
|
SQL table names should be all-lowercase and include underscores to
|
||||||
|
separate words. This is because SQL itself is case-insensitive.
|
||||||
|
This doesn't change, however the fact that variable/member names
|
||||||
|
should be camel case.
|
||||||
|
|
||||||
|
SQL statements in code should put SQL words in ALL CAPS:
|
||||||
|
"""SELECT quote FROM quotes ORDER BY random() LIMIT 1""". This makes
|
||||||
|
SQL significantly easier to read.
|
||||||
|
|
||||||
|
Common variable names:
|
||||||
|
L => an arbitrary list.
|
||||||
|
t => an arbitrary tuple.
|
||||||
|
x => an arbitrary float.
|
||||||
|
s => an arbitrary string.
|
||||||
|
f => an arbitrary function.
|
||||||
|
p => an arbitrary predicate.
|
||||||
|
i,n => an arbitrary integer.
|
||||||
|
cb => an arbitrary callback.
|
||||||
|
db => a database handle.
|
||||||
|
fd => a file-like object.
|
||||||
|
msg => an ircmsgs.IrcMsg object.
|
||||||
|
irc => an irclib.Irc object (or proxy)
|
||||||
|
nick => a string that is an IRC nick.
|
||||||
|
channel => a string that is an IRC channel.
|
||||||
|
hostmask => a string that is a user's IRC prefix.
|
||||||
|
When the semantic functionality (that is, the "meaning" of a variable
|
||||||
|
is obvious from context, one of these names should be used. This
|
||||||
|
just makes it easier for people reading our code to know what a
|
||||||
|
variable represents without scouring the surrounding code.
|
||||||
|
|
||||||
|
Multiple variable assignments should always be surrounded with
|
||||||
|
parentheses -- i.e., if you're using the partition function, then
|
||||||
|
your assignment statement should look like
|
||||||
|
(good, bad) = partition(p, L). The parentheses make it obvious that
|
||||||
|
you're doing a multiple assignment, and that's important because I
|
||||||
|
hate reading code and wondering where a variable came from.
|
||||||
43
docs/man/supybot-adduser.1
Normal file
43
docs/man/supybot-adduser.1
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
.\" Process this file with
|
||||||
|
.\" groff -man -Tascii supybot-adduser.1
|
||||||
|
.\"
|
||||||
|
.TH SUPYBOT\-ADDUSER 1 "SEPTEMBER 2004"
|
||||||
|
.SH NAME
|
||||||
|
supybot\-adduser \- Adds a user to a Supybot users.conf file
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B supybot\-adduser
|
||||||
|
.RI [ options ] " users.conf
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B
|
||||||
|
supybot\-adduser
|
||||||
|
adds a user to the specified users.conf file.
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP
|
||||||
|
.B \-\^\-version
|
||||||
|
Show version of program.
|
||||||
|
.TP
|
||||||
|
.BR \-h ", " \-\^\-help
|
||||||
|
Show summary of options.
|
||||||
|
.TP
|
||||||
|
.BR \-u " NAME" "\fR,\fP \-\^\-username=" NAME
|
||||||
|
Specifies the username to use for the new user.
|
||||||
|
.TP
|
||||||
|
.BR \-x ", " \-\^\-hashed
|
||||||
|
Hash encrypt the password.
|
||||||
|
.TP
|
||||||
|
.BR \-n ", " \-\^\-plain
|
||||||
|
Store the password in plain text.
|
||||||
|
.TP
|
||||||
|
.BR \-c " CAPABILITY" "\fR,\fP \-\^\-capability=" CAPABILITY
|
||||||
|
Capability the user should have; this option may be given
|
||||||
|
multiple times.
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.IR python (1),
|
||||||
|
.IR supybot (1),
|
||||||
|
.IR supybot\-wizard (1),
|
||||||
|
.IR supybot\-newplugin (1)
|
||||||
|
.SH AUTHOR
|
||||||
|
This manual page was originally written by James Vega
|
||||||
|
<vega dot james at gmail dot com>. Permission is granted to copy,
|
||||||
|
distribute and/or modify this document under the terms of the Supybot
|
||||||
|
license, a BSD\-style license.
|
||||||
41
docs/man/supybot-newplugin.1
Normal file
41
docs/man/supybot-newplugin.1
Normal file
@ -0,0 +1,41 @@
|
|||||||
|
.\" Process this file with
|
||||||
|
.\" groff -man -Tascii supybot-newplugin.1
|
||||||
|
.\"
|
||||||
|
.TH SUPYBOT\-NEWPLUGIN 1 "SEPTEMBER 2004"
|
||||||
|
.SH NAME
|
||||||
|
supybot\-newplugin \- A wizard for creating Supybot plugins
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B supybot\-newplugin
|
||||||
|
.RI [ options ]
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B
|
||||||
|
supybot\-newplugin
|
||||||
|
is a wizard that creates a template python source file for a new
|
||||||
|
.IR supybot (1)
|
||||||
|
plugin.
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP
|
||||||
|
.B \-\^\-version
|
||||||
|
Show version of program.
|
||||||
|
.TP
|
||||||
|
.BR \-h ", " \-\^\-help
|
||||||
|
Show summary of options.
|
||||||
|
.TP
|
||||||
|
.BR \-r ", " \-\^\-regexp
|
||||||
|
Uses a regexp\-based callback.
|
||||||
|
.TP
|
||||||
|
.BI \-n " NAME" "\fR,\fP \-\^\-name=" NAME
|
||||||
|
Sets the name for the plugin.
|
||||||
|
.TP
|
||||||
|
.BR \-t ", " \-\^\-thread
|
||||||
|
Makes the plugin threaded.
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.IR python (1),
|
||||||
|
.IR supybot (1),
|
||||||
|
.IR supybot\-wizard (1),
|
||||||
|
.IR supybot\-adduser (1),
|
||||||
|
.SH AUTHOR
|
||||||
|
This manual page was originally written by James Vega
|
||||||
|
<vega dot james at gmail dot com>. Permission is granted to copy,
|
||||||
|
distribute and/or modify this document under the terms of the Supybot
|
||||||
|
license, a BSD\-style license.
|
||||||
40
docs/man/supybot-wizard.1
Normal file
40
docs/man/supybot-wizard.1
Normal file
@ -0,0 +1,40 @@
|
|||||||
|
.\" Process this file with
|
||||||
|
.\" groff -man -Tascii supybot-wizard.1
|
||||||
|
.\"
|
||||||
|
.TH SUPYBOT\-WIZARD 1 "SEPTEMBER 2004"
|
||||||
|
.SH NAME
|
||||||
|
supybot\-wizard \- A wizard for creating Supybot configuration files
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B supybot\-wizard
|
||||||
|
.RI [ options ]
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B
|
||||||
|
supybot\-wizard
|
||||||
|
is an in\-depth wizard that provides a nice user interface for creating
|
||||||
|
configuration files for
|
||||||
|
.IR supybot (1).
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP
|
||||||
|
.B \-\^\-version
|
||||||
|
Show version of program.
|
||||||
|
.TP
|
||||||
|
.BR \-h ", " \-\^\-help
|
||||||
|
Show summary of options.
|
||||||
|
.TP
|
||||||
|
.B \-\^\-allow\-root
|
||||||
|
Determines whether the wizard will be allowed to run as root. You do not
|
||||||
|
want this. Do not do it. Even if you think you want it, you do not.
|
||||||
|
.TP
|
||||||
|
.B \-\^\-no\-network
|
||||||
|
Determines whether the wizard will be allowed to run without a network
|
||||||
|
connection.
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.IR python (1),
|
||||||
|
.IR supybot (1),
|
||||||
|
.IR supybot\-adduser (1),
|
||||||
|
.IR supybot\-newplugin (1)
|
||||||
|
.SH AUTHOR
|
||||||
|
This manual page was originally written by James Vega
|
||||||
|
<vega dot james at gmail dot com>. Permission is granted to copy,
|
||||||
|
distribute and/or modify this document under the terms of the Supybot
|
||||||
|
license, a BSD\-style license.
|
||||||
68
docs/man/supybot.1
Normal file
68
docs/man/supybot.1
Normal file
@ -0,0 +1,68 @@
|
|||||||
|
.\" Process this file with
|
||||||
|
.\" groff -man -Tascii supybot.1
|
||||||
|
.\"
|
||||||
|
.TH SUPYBOT 1 "SEPTEMBER 2004"
|
||||||
|
.SH NAME
|
||||||
|
supybot \- A robust and user friendly Python IRC bot
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B supybot
|
||||||
|
.RI [ options ] " configFile
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B
|
||||||
|
Supybot
|
||||||
|
is a robust, user\-friendly, and programmer\-friendly Python IRC bot.
|
||||||
|
It aims to be an adequate replacement for most existing IRC bots. It
|
||||||
|
includes a very flexible and powerful ACL system for controlling access
|
||||||
|
to commands, as well as more than 50 builtin plugins providing around
|
||||||
|
400 actual commands.
|
||||||
|
.SH OPTIONS
|
||||||
|
.TP
|
||||||
|
.B \-\^\-version
|
||||||
|
Show version of program.
|
||||||
|
.TP
|
||||||
|
.BR \-h ", " \-\^\-help
|
||||||
|
Show summary of options.
|
||||||
|
.TP
|
||||||
|
.BR \-P ", " \-\^\-profile
|
||||||
|
Enable profiling.
|
||||||
|
.TP
|
||||||
|
.B \-O
|
||||||
|
Optimizes asserts out of the code; \-O0 optimizes asserts and uses
|
||||||
|
.IR psyco .
|
||||||
|
.TP
|
||||||
|
.BI \-n " NICK" "\fR,\fP \-\^\-nick=" NICK
|
||||||
|
Nick the bot should use.
|
||||||
|
.TP
|
||||||
|
.BI \-u " USER" "\fR,\fP \-\^\-user=" USER
|
||||||
|
Full username the bot should use.
|
||||||
|
.TP
|
||||||
|
.BI \-i " IDENT" "\fR,\fP \-\^\-ident=" IDENT
|
||||||
|
Ident the bot should use.
|
||||||
|
.TP
|
||||||
|
.BR \-d ", " \-\^\-daemon
|
||||||
|
Determines whether the bot will daemonize. This is a no\-op on
|
||||||
|
non\-POSIX systems.
|
||||||
|
.TP
|
||||||
|
.B \-\^\-allow\-default\-owner
|
||||||
|
Determines whether the bot will allow its defaultCapabilities not to
|
||||||
|
include "\-owner", thus giving all users the owner capability by
|
||||||
|
default. This is dumb, hence we require a command\-line option to
|
||||||
|
enable it.
|
||||||
|
.TP
|
||||||
|
.B \-\^\-allow\-root
|
||||||
|
Determines whether the bot will be allowed to run as root. You do not
|
||||||
|
want this. Do not do it. Even if you think you want it, you do not.
|
||||||
|
.TP
|
||||||
|
.B \-\^\-debug
|
||||||
|
Determines whether some extra debugging stuff will be logged by this
|
||||||
|
script.
|
||||||
|
.SH "SEE ALSO"
|
||||||
|
.IR python (1),
|
||||||
|
.IR supybot\-wizard (1),
|
||||||
|
.IR supybot\-adduser (1),
|
||||||
|
.IR supybot\-newplugin (1)
|
||||||
|
.SH AUTHOR
|
||||||
|
This manual page was originally written by James Vega
|
||||||
|
<vega dot james at gmail dot com>. Permission is granted to copy,
|
||||||
|
distribute and/or modify this document under the terms of the Supybot
|
||||||
|
license, a BSD\-style license.
|
||||||
30
feed.xml
30
feed.xml
@ -1,30 +0,0 @@
|
|||||||
---
|
|
||||||
layout: null
|
|
||||||
---
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
|
||||||
<channel>
|
|
||||||
<title>{{ site.title | xml_escape }}</title>
|
|
||||||
<description>{{ site.description | xml_escape }}</description>
|
|
||||||
<link>{{ site.url }}{{ site.baseurl }}/</link>
|
|
||||||
<atom:link href="{{ "/feed.xml" | prepend: site.baseurl | prepend: site.url }}" rel="self" type="application/rss+xml"/>
|
|
||||||
<pubDate>{{ site.time | date_to_rfc822 }}</pubDate>
|
|
||||||
<lastBuildDate>{{ site.time | date_to_rfc822 }}</lastBuildDate>
|
|
||||||
<generator>Jekyll v{{ jekyll.version }}</generator>
|
|
||||||
{% for post in site.posts limit:10 %}
|
|
||||||
<item>
|
|
||||||
<title>{{ post.title | xml_escape }}</title>
|
|
||||||
<description>{{ post.content | xml_escape }}</description>
|
|
||||||
<pubDate>{{ post.date | date_to_rfc822 }}</pubDate>
|
|
||||||
<link>{{ post.url | prepend: site.baseurl | prepend: site.url }}</link>
|
|
||||||
<guid isPermaLink="true">{{ post.url | prepend: site.baseurl | prepend: site.url }}</guid>
|
|
||||||
{% for tag in post.tags %}
|
|
||||||
<category>{{ tag | xml_escape }}</category>
|
|
||||||
{% endfor %}
|
|
||||||
{% for cat in post.categories %}
|
|
||||||
<category>{{ cat | xml_escape }}</category>
|
|
||||||
{% endfor %}
|
|
||||||
</item>
|
|
||||||
{% endfor %}
|
|
||||||
</channel>
|
|
||||||
</rss>
|
|
||||||
@ -1,26 +0,0 @@
|
|||||||
---
|
|
||||||
layout: default
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- @format -->
|
|
||||||
|
|
||||||
**_WARNING: most of the content on this site originates from 2014!_**
|
|
||||||
|
|
||||||
Welcome to Mikaela's Supybot pages.
|
|
||||||
|
|
||||||
This site isn't official and won't help with most of issues. In case you are
|
|
||||||
looking for the official sites, they are here:
|
|
||||||
|
|
||||||
- [Limnoria's website](https://limnoria.net/)
|
|
||||||
- [Limnoria official documentation](https://docs.limnoria.net/)
|
|
||||||
- [Supybook](https://hoxu.github.io/supybook/devel/)
|
|
||||||
- [Gribble Wiki](https://sourceforge.net/p/gribble/wiki/Main_Page/)
|
|
||||||
|
|
||||||
I also have
|
|
||||||
[something in my gist repo](https://gitea.blesmrt.net/mikaela/gist/src/branch/master/irc/limnoria/)
|
|
||||||
at 2021-06-11 16:07 UTC
|
|
||||||
[opinionated titlefetching instructions](https://gitea.blesmrt.net/mikaela/gist/src/branch/master/irc/limnoria/titlefetching.md).
|
|
||||||
|
|
||||||
If you cannot find what you are looking for from them, please come to IRC and
|
|
||||||
ask. The Support channels are
|
|
||||||
[#supybot,#limnoria on irc.libera.chat](ircs://irc.libera.chat:6697/%23supybot%2c%23limnoria)
|
|
||||||
450
others/BeautifulSoup.py
Normal file
450
others/BeautifulSoup.py
Normal file
@ -0,0 +1,450 @@
|
|||||||
|
"""Beautiful Soup
|
||||||
|
Elixir and Tonic
|
||||||
|
"The Screen-Scraper's Friend"
|
||||||
|
|
||||||
|
The BeautifulSoup class turns arbitrarily bad HTML into a tree-like
|
||||||
|
nested tag-soup list of Tag objects and text snippets. A Tag object
|
||||||
|
corresponds to an HTML tag. It knows about the HTML tag's attributes,
|
||||||
|
and contains a representation of everything contained between the
|
||||||
|
original tag and its closing tag (if any). It's easy to extract Tags
|
||||||
|
that meet certain criteria.
|
||||||
|
|
||||||
|
A well-formed HTML document will yield a well-formed data
|
||||||
|
structure. An ill-formed HTML document will yield a correspondingly
|
||||||
|
ill-formed data structure. If your document is only locally
|
||||||
|
well-formed, you can use this to process the well-formed part of it.
|
||||||
|
|
||||||
|
#Example:
|
||||||
|
#--------
|
||||||
|
from BeautifulSoup import BeautifulSoup
|
||||||
|
text = '''<html>
|
||||||
|
<head><title>The Title</title></head>
|
||||||
|
<body>
|
||||||
|
<a class="foo" href="http://www.crummy.com/">Link <i>text (italicized)</i></a>
|
||||||
|
<a href="http://www.foo.com/">Link text 2</a>
|
||||||
|
</body>
|
||||||
|
</html>'''
|
||||||
|
soup = BeautifulSoup()
|
||||||
|
soup.feed(text)
|
||||||
|
print soup("a") #Returns a list of 2 Tag objects, one for each link in
|
||||||
|
#the source
|
||||||
|
print soup.first("a", {'class':'foo'})['href'] #Returns http://www.crummy.com/
|
||||||
|
print soup.first("title").contents[0] #Returns "The title"
|
||||||
|
print soup.first("a", {'href':'http://www.crummy.com/'}).first("i").contents[0]
|
||||||
|
#Returns "text (italicized)"
|
||||||
|
|
||||||
|
#Example of SQL-style attribute wildcards -- all four 'find' calls will
|
||||||
|
#find the link.
|
||||||
|
#----------------------------------------------------------------------
|
||||||
|
soup = BeautifulSoup()
|
||||||
|
soup.feed('''<a href="http://foo.com/">bla</a>''')
|
||||||
|
print soup.fetch('a', {'href': 'http://foo.com/'})
|
||||||
|
print soup.fetch('a', {'href': 'http://%'})
|
||||||
|
print soup.fetch('a', {'href': '%.com/'})
|
||||||
|
print soup.fetch('a', {'href': '%o.c%'})
|
||||||
|
|
||||||
|
#Example with horrible HTML:
|
||||||
|
#---------------------------
|
||||||
|
soup = BeautifulSoup()
|
||||||
|
soup.feed('''<body>
|
||||||
|
Go <a class="that" href="here.html"><i>here</i></a>
|
||||||
|
or <i>go <b><a href="index.html">Home</a>
|
||||||
|
</html>''')
|
||||||
|
print soup.fetch('a') #Returns a list of 2 Tag objects.
|
||||||
|
print soup.first(attrs={'href': 'here.html'})['class'] #Returns "that"
|
||||||
|
print soup.first(attrs={'class': 'that'}).first('i').contents[0] #returns "here"
|
||||||
|
|
||||||
|
This library has no external dependencies. It works with Python 1.5.2
|
||||||
|
and up. If you can install a Python extension, you might want to use
|
||||||
|
the ElementTree Tidy HTML Tree Builder instead:
|
||||||
|
http://www.effbot.org/zone/element-tidylib.htm
|
||||||
|
|
||||||
|
You can use BeautifulSoup on any SGML-like substance, such as XML or a
|
||||||
|
domain-specific language that looks like HTML but has different tag
|
||||||
|
names. For such purposes you may want to use the BeautifulStoneSoup
|
||||||
|
class, which knows nothing at all about HTML per se. I also reserve
|
||||||
|
the right to make the BeautifulSoup parser smarter between releases,
|
||||||
|
so if you want forwards-compatibility without having to think about
|
||||||
|
it, you might want to go with BeautifulStoneSoup.
|
||||||
|
|
||||||
|
Release status:
|
||||||
|
|
||||||
|
(I do a new release whenever I make a change that breaks backwards
|
||||||
|
compatibility.)
|
||||||
|
|
||||||
|
Current release:
|
||||||
|
|
||||||
|
Applied patch from Richie Hindle (richie at entrian dot com) that
|
||||||
|
makes tag.string a shorthand for tag.contents[0].string when the tag
|
||||||
|
has only one string-owning child.
|
||||||
|
|
||||||
|
1.2 "Who for such dainties would not stoop?" (2004/07/08): Applied
|
||||||
|
patch from Ben Last (ben at benlast dot com) that made
|
||||||
|
Tag.renderContents() correctly handle Unicode.
|
||||||
|
|
||||||
|
Made BeautifulStoneSoup even dumber by making it not implicitly
|
||||||
|
close a tag when another tag of the same type is encountered; only
|
||||||
|
when an actual closing tag is encountered. This change courtesy of
|
||||||
|
Fuzzy (mike at pcblokes dot com). BeautifulSoup still works as
|
||||||
|
before.
|
||||||
|
|
||||||
|
1.1 "Swimming in a hot tureen": Added more 'nestable' tags. Changed
|
||||||
|
popping semantics so that when a nestable tag is encountered, tags are
|
||||||
|
popped up to the previously encountered nestable tag (of whatever kind).
|
||||||
|
I will revert this if enough people complain, but it should make
|
||||||
|
more people's lives easier than harder.
|
||||||
|
|
||||||
|
This enhancement was suggested by Anthony Baxter (anthony at
|
||||||
|
interlink dot com dot au).
|
||||||
|
|
||||||
|
1.0 "So rich and green": Initial release.
|
||||||
|
|
||||||
|
Retreived from: http://www.crummy.com/software/BeautifulSoup/
|
||||||
|
"""
|
||||||
|
|
||||||
|
__author__ = "Leonard Richardson (leonardr@segfault.org)"
|
||||||
|
__version__ = "1.1 $Revision$"
|
||||||
|
__date__ = "$Date$"
|
||||||
|
__copyright__ = "Copyright (c) 2004 Leonard Richardson"
|
||||||
|
__license__ = "Python"
|
||||||
|
|
||||||
|
from sgmllib import SGMLParser
|
||||||
|
import string
|
||||||
|
import types
|
||||||
|
|
||||||
|
class PageElement:
|
||||||
|
"""Contains the navigational information for some part of the page
|
||||||
|
(either a tag or a piece of text)"""
|
||||||
|
|
||||||
|
def __init__(self, parent=None, previous=None):
|
||||||
|
self.parent = parent
|
||||||
|
self.previous = previous
|
||||||
|
self.next = None
|
||||||
|
|
||||||
|
class NavigableText(PageElement):
|
||||||
|
|
||||||
|
"""A simple wrapper around a string that keeps track of where in
|
||||||
|
the document the string was found. Doesn't implement all the
|
||||||
|
string methods because I'm lazy. You could have this extend
|
||||||
|
UserString if you were using 2.2."""
|
||||||
|
|
||||||
|
def __init__(self, string, parent=None, previous=None):
|
||||||
|
PageElement.__init__(self, parent, previous)
|
||||||
|
self.string = string
|
||||||
|
|
||||||
|
def __eq__(self, other):
|
||||||
|
return self.string == str(other)
|
||||||
|
|
||||||
|
def __str__(self):
|
||||||
|
return self.string
|
||||||
|
|
||||||
|
def strip(self):
|
||||||
|
return self.string.strip()
|
||||||
|
|
||||||
|
class Tag(PageElement):
|
||||||
|
|
||||||
|
"""Represents a found HTML tag with its attributes and contents."""
|
||||||
|
|
||||||
|
def __init__(self, name, attrs={}, parent=None, previous=None):
|
||||||
|
PageElement.__init__(self, parent, previous)
|
||||||
|
self.name = name
|
||||||
|
self.attrs = attrs
|
||||||
|
self.contents = []
|
||||||
|
self.foundClose = 0
|
||||||
|
|
||||||
|
def get(self, key, default=None):
|
||||||
|
return self._getAttrMap().get(key, default)
|
||||||
|
|
||||||
|
def __call__(self, *args):
|
||||||
|
return apply(self.fetch, args)
|
||||||
|
|
||||||
|
def __getitem__(self, key):
|
||||||
|
return self._getAttrMap()[key]
|
||||||
|
|
||||||
|
def __setitem__(self, key, value):
|
||||||
|
self._getAttrMap()
|
||||||
|
self.attrMap[key] = value
|
||||||
|
for i in range(0, len(self.attrs)):
|
||||||
|
if self.attrs[i][0] == key:
|
||||||
|
self.attrs[i] = (key, value)
|
||||||
|
|
||||||
|
def _getAttrMap(self):
|
||||||
|
if not hasattr(self, 'attrMap'):
|
||||||
|
self.attrMap = {}
|
||||||
|
for (key, value) in self.attrs:
|
||||||
|
self.attrMap[key] = value
|
||||||
|
return self.attrMap
|
||||||
|
|
||||||
|
def __repr__(self):
|
||||||
|
return str(self)
|
||||||
|
|
||||||
|
def __ne__(self, other):
|
||||||
|
return not self == other
|
||||||
|
|
||||||
|
def __eq__(self, other):
|
||||||
|
if not isinstance(other, Tag) or self.name != other.name or self.attrs != other.attrs or len(self.contents) != len(other.contents):
|
||||||
|
return 0
|
||||||
|
for i in range(0, len(self.contents)):
|
||||||
|
if self.contents[i] != other.contents[i]:
|
||||||
|
return 0
|
||||||
|
return 1
|
||||||
|
|
||||||
|
def __str__(self):
|
||||||
|
attrs = ''
|
||||||
|
if self.attrs:
|
||||||
|
for key, val in self.attrs:
|
||||||
|
attrs = attrs + ' %s="%s"' % (key, val)
|
||||||
|
close = ''
|
||||||
|
closeTag = ''
|
||||||
|
if self.isSelfClosing():
|
||||||
|
close = ' /'
|
||||||
|
elif self.foundClose:
|
||||||
|
closeTag = '</%s>' % self.name
|
||||||
|
s = self.renderContents()
|
||||||
|
if not hasattr(self, 'hideTag'):
|
||||||
|
s = '<%s%s%s>' % (self.name, attrs, close) + s + closeTag
|
||||||
|
return s
|
||||||
|
|
||||||
|
def renderContents(self):
|
||||||
|
s='' #non-Unicode
|
||||||
|
for c in self.contents:
|
||||||
|
try:
|
||||||
|
s = s + str(c)
|
||||||
|
except UnicodeEncodeError:
|
||||||
|
if type(s) <> types.UnicodeType:
|
||||||
|
s = s.decode('utf8') #convert ascii to Unicode
|
||||||
|
#str() should, strictly speaking, not return a Unicode
|
||||||
|
#string, but NavigableText never checks and will return
|
||||||
|
#Unicode data if it was initialised with it.
|
||||||
|
s = s + str(c)
|
||||||
|
return s
|
||||||
|
|
||||||
|
def isSelfClosing(self):
|
||||||
|
return self.name in BeautifulSoup.SELF_CLOSING_TAGS
|
||||||
|
|
||||||
|
def append(self, tag):
|
||||||
|
self.contents.append(tag)
|
||||||
|
|
||||||
|
def first(self, name=None, attrs={}, contents=None, recursive=1):
|
||||||
|
r = None
|
||||||
|
l = self.fetch(name, attrs, contents, recursive)
|
||||||
|
if l:
|
||||||
|
r = l[0]
|
||||||
|
return r
|
||||||
|
|
||||||
|
def fetch(self, name=None, attrs={}, contents=None, recursive=1):
|
||||||
|
"""Extracts Tag objects that match the given criteria. You
|
||||||
|
can specify the name of the Tag, any attributes you want the
|
||||||
|
Tag to have, and what text and Tags you want to see inside the
|
||||||
|
Tag."""
|
||||||
|
if contents and type(contents) != type([]):
|
||||||
|
contents = [contents]
|
||||||
|
results = []
|
||||||
|
for i in self.contents:
|
||||||
|
if isinstance(i, Tag):
|
||||||
|
if not name or i.name == name:
|
||||||
|
match = 1
|
||||||
|
for attr, value in attrs.items():
|
||||||
|
check = i.get(attr)
|
||||||
|
#By default, find the specific value called for.
|
||||||
|
#Use SQL-style wildcards to find substrings, prefix,
|
||||||
|
#suffix, etc.
|
||||||
|
result = (check == value)
|
||||||
|
if check and value:
|
||||||
|
if len(value) > 1 and value[0] == '%' and value[-1] == '%' and value[-2] != '\\':
|
||||||
|
result = (check.find(value[1:-1]) != -1)
|
||||||
|
elif value[0] == '%':
|
||||||
|
print "blah"
|
||||||
|
result = check.rfind(value[1:]) == len(check)-len(value)+1
|
||||||
|
elif value[-1] == '%':
|
||||||
|
result = check.find(value[:-1]) == 0
|
||||||
|
if not result:
|
||||||
|
match = 0
|
||||||
|
break
|
||||||
|
match = match and (not contents or i.contents == contents)
|
||||||
|
if match:
|
||||||
|
results.append(i)
|
||||||
|
if recursive:
|
||||||
|
results.extend(i.fetch(name, attrs, contents, recursive))
|
||||||
|
return results
|
||||||
|
|
||||||
|
class BeautifulSoup(SGMLParser, Tag):
|
||||||
|
|
||||||
|
"""The actual parser. It knows the following facts about HTML, and
|
||||||
|
not much else:
|
||||||
|
|
||||||
|
* Some tags have no closing tag and should be interpreted as being
|
||||||
|
closed as soon as they are encountered.
|
||||||
|
|
||||||
|
* Most tags can't be nested; encountering an open tag when there's
|
||||||
|
already an open tag of that type in the stack means that the
|
||||||
|
previous tag of that type should be implicitly closed. However,
|
||||||
|
some tags can be nested. When a nestable tag is encountered,
|
||||||
|
it's okay to close all unclosed tags up to the last nestable
|
||||||
|
tag. It might not be safe to close any more, so that's all it
|
||||||
|
closes.
|
||||||
|
|
||||||
|
* The text inside some tags (ie. 'script') may contain tags which
|
||||||
|
are not really part of the document and which should be parsed
|
||||||
|
as text, not tags. If you want to parse the text as tags, you can
|
||||||
|
always get it and parse it explicitly."""
|
||||||
|
|
||||||
|
SELF_CLOSING_TAGS = ['br', 'hr', 'input', 'img', 'meta', 'spacer',
|
||||||
|
'link', 'frame']
|
||||||
|
NESTABLE_TAGS = ['font', 'table', 'tr', 'td', 'th', 'tbody', 'p',
|
||||||
|
'div']
|
||||||
|
QUOTE_TAGS = ['script']
|
||||||
|
|
||||||
|
IMPLICITLY_CLOSE_TAGS = 1
|
||||||
|
|
||||||
|
def __init__(self, text=None):
|
||||||
|
Tag.__init__(self, '[document]')
|
||||||
|
SGMLParser.__init__(self)
|
||||||
|
self.quoteStack = []
|
||||||
|
self.hideTag = 1
|
||||||
|
self.reset()
|
||||||
|
if text:
|
||||||
|
self.feed(text)
|
||||||
|
|
||||||
|
def feed(self, text):
|
||||||
|
SGMLParser.feed(self, text)
|
||||||
|
self.endData()
|
||||||
|
|
||||||
|
def reset(self):
|
||||||
|
SGMLParser.reset(self)
|
||||||
|
self.currentData = ''
|
||||||
|
self.currentTag = None
|
||||||
|
self.tagStack = []
|
||||||
|
self.pushTag(self)
|
||||||
|
|
||||||
|
def popTag(self, closedTagName=None):
|
||||||
|
tag = self.tagStack.pop()
|
||||||
|
if closedTagName == tag.name:
|
||||||
|
tag.foundClose = 1
|
||||||
|
|
||||||
|
# Tags with just one string-owning child get the same string
|
||||||
|
# property as the child, so that soup.tag.string is shorthand
|
||||||
|
# for soup.tag.contents[0].string
|
||||||
|
if len(self.currentTag.contents) == 1 and \
|
||||||
|
hasattr(self.currentTag.contents[0], 'string'):
|
||||||
|
self.currentTag.string = self.currentTag.contents[0].string
|
||||||
|
|
||||||
|
#print "Pop", tag.name
|
||||||
|
self.currentTag = self.tagStack[-1]
|
||||||
|
return self.currentTag
|
||||||
|
|
||||||
|
def pushTag(self, tag):
|
||||||
|
#print "Push", tag.name
|
||||||
|
if self.currentTag:
|
||||||
|
self.currentTag.append(tag)
|
||||||
|
self.tagStack.append(tag)
|
||||||
|
self.currentTag = self.tagStack[-1]
|
||||||
|
|
||||||
|
def endData(self):
|
||||||
|
if self.currentData:
|
||||||
|
if not string.strip(self.currentData):
|
||||||
|
if '\n' in self.currentData:
|
||||||
|
self.currentData = '\n'
|
||||||
|
else:
|
||||||
|
self.currentData = ' '
|
||||||
|
o = NavigableText(self.currentData, self.currentTag, self.previous)
|
||||||
|
if self.previous:
|
||||||
|
self.previous.next = o
|
||||||
|
self.previous = o
|
||||||
|
self.currentTag.contents.append(o)
|
||||||
|
self.currentData = ''
|
||||||
|
|
||||||
|
def _popToTag(self, name, closedTag=0):
|
||||||
|
"""Pops the tag stack up to and including the most recent
|
||||||
|
instance of the given tag. If a list of tags is given, will
|
||||||
|
accept any of those tags as an excuse to stop popping, and will
|
||||||
|
*not* pop the tag that caused it to stop popping."""
|
||||||
|
if self.IMPLICITLY_CLOSE_TAGS:
|
||||||
|
closedTag = 1
|
||||||
|
numPops = 0
|
||||||
|
mostRecentTag = None
|
||||||
|
oneTag = (type(name) == types.StringType)
|
||||||
|
for i in range(len(self.tagStack)-1, 0, -1):
|
||||||
|
thisTag = self.tagStack[i].name
|
||||||
|
if (oneTag and thisTag == name) \
|
||||||
|
or (not oneTag and thisTag in name):
|
||||||
|
numPops = len(self.tagStack)-i
|
||||||
|
break
|
||||||
|
if not oneTag:
|
||||||
|
numPops = numPops - 1
|
||||||
|
|
||||||
|
closedTagName = None
|
||||||
|
if closedTag:
|
||||||
|
closedTagName = name
|
||||||
|
|
||||||
|
for i in range(0, numPops):
|
||||||
|
mostRecentTag = self.popTag(closedTagName)
|
||||||
|
return mostRecentTag
|
||||||
|
|
||||||
|
def unknown_starttag(self, name, attrs):
|
||||||
|
if self.quoteStack:
|
||||||
|
#This is not a real tag.
|
||||||
|
#print "<%s> is not real!" % name
|
||||||
|
attrs = map(lambda(x, y): '%s="%s"' % (x, y), attrs)
|
||||||
|
self.handle_data('<%s %s>' % (name, attrs))
|
||||||
|
return
|
||||||
|
self.endData()
|
||||||
|
tag = Tag(name, attrs, self.currentTag, self.previous)
|
||||||
|
if self.previous:
|
||||||
|
self.previous.next = tag
|
||||||
|
self.previous = tag
|
||||||
|
if not name in self.SELF_CLOSING_TAGS:
|
||||||
|
if name in self.NESTABLE_TAGS:
|
||||||
|
self._popToTag(self.NESTABLE_TAGS)
|
||||||
|
else:
|
||||||
|
self._popToTag(name)
|
||||||
|
self.pushTag(tag)
|
||||||
|
if name in self.SELF_CLOSING_TAGS:
|
||||||
|
self.popTag()
|
||||||
|
if name in self.QUOTE_TAGS:
|
||||||
|
#print "Beginning quote (%s)" % name
|
||||||
|
self.quoteStack.append(name)
|
||||||
|
|
||||||
|
def unknown_endtag(self, name):
|
||||||
|
if self.quoteStack and self.quoteStack[-1] != name:
|
||||||
|
#This is not a real end tag.
|
||||||
|
#print "</%s> is not real!" % name
|
||||||
|
self.handle_data('</%s>' % name)
|
||||||
|
return
|
||||||
|
self.endData()
|
||||||
|
self._popToTag(name, 1)
|
||||||
|
if self.quoteStack and self.quoteStack[-1] == name:
|
||||||
|
#print "That's the end of %s!" % self.quoteStack[-1]
|
||||||
|
self.quoteStack.pop()
|
||||||
|
|
||||||
|
def handle_data(self, data):
|
||||||
|
self.currentData = self.currentData + data
|
||||||
|
|
||||||
|
def handle_comment(self, text):
|
||||||
|
"Propagate comments right through."
|
||||||
|
self.handle_data("<!--%s-->" % text)
|
||||||
|
|
||||||
|
def handle_charref(self, ref):
|
||||||
|
"Propagate char refs right through."
|
||||||
|
self.handle_data('&#%s;' % ref)
|
||||||
|
|
||||||
|
def handle_entityref(self, ref):
|
||||||
|
"Propagate entity refs right through."
|
||||||
|
self.handle_data('&%s;' % ref)
|
||||||
|
|
||||||
|
def handle_decl(self, data):
|
||||||
|
"Propagate DOCTYPEs right through."
|
||||||
|
self.handle_data('<!%s>' % data)
|
||||||
|
|
||||||
|
class BeautifulStoneSoup(BeautifulSoup):
|
||||||
|
|
||||||
|
"""A version of BeautifulSoup that doesn't know anything at all
|
||||||
|
about what HTML tags have special behavior. Useful for parsing
|
||||||
|
things that aren't HTML, or when BeautifulSoup makes an assumption
|
||||||
|
counter to what you were expecting."""
|
||||||
|
|
||||||
|
IMPLICITLY_CLOSE_TAGS = 0
|
||||||
|
|
||||||
|
SELF_CLOSING_TAGS = []
|
||||||
|
NESTABLE_TAGS = []
|
||||||
|
QUOTE_TAGS = []
|
||||||
85
others/GoogleSOAPFacade.py
Normal file
85
others/GoogleSOAPFacade.py
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
"""
|
||||||
|
Facade that hides the differences between the SOAPpy and SOAP.py
|
||||||
|
libraries, so that google.py doesn't have to deal with them.
|
||||||
|
|
||||||
|
@author: Brian Landers <brian@bluecoat93.org>
|
||||||
|
@license: Python
|
||||||
|
@version: 0.5.4
|
||||||
|
"""
|
||||||
|
|
||||||
|
import warnings
|
||||||
|
from distutils.version import LooseVersion
|
||||||
|
|
||||||
|
__author__ = "Brian Landers <brian@bluecoat93.org>"
|
||||||
|
__version__ = "0.6"
|
||||||
|
__license__ = "Python"
|
||||||
|
|
||||||
|
#
|
||||||
|
# Wrapper around the python 'warnings' facility
|
||||||
|
#
|
||||||
|
def warn( message, level=RuntimeWarning ):
|
||||||
|
warnings.warn( message, level, stacklevel=3 )
|
||||||
|
|
||||||
|
# We can't use older version of SOAPpy, due to bugs that break the Google API
|
||||||
|
minSOAPpyVersion = "0.11.3"
|
||||||
|
|
||||||
|
#
|
||||||
|
# Try loading SOAPpy first. If that fails, fall back to the old SOAP.py
|
||||||
|
#
|
||||||
|
SOAPpy = None
|
||||||
|
try:
|
||||||
|
import SOAPpy
|
||||||
|
from SOAPpy import SOAPProxy, Types
|
||||||
|
|
||||||
|
if LooseVersion( minSOAPpyVersion ) > \
|
||||||
|
LooseVersion( SOAPpy.version.__version__ ):
|
||||||
|
|
||||||
|
warn( "Versions of SOAPpy before %s have known bugs that prevent " +
|
||||||
|
"PyGoogle from functioning." % minSOAPpyVersion )
|
||||||
|
raise ImportError
|
||||||
|
|
||||||
|
except ImportError:
|
||||||
|
warn( "SOAPpy not imported. Trying legacy SOAP.py.",
|
||||||
|
DeprecationWarning )
|
||||||
|
try:
|
||||||
|
import SOAP
|
||||||
|
except ImportError:
|
||||||
|
raise RuntimeError( "Unable to find SOAPpy or SOAP. Can't continue.\n" )
|
||||||
|
|
||||||
|
#
|
||||||
|
# Constants that differ between the modules
|
||||||
|
#
|
||||||
|
if SOAPpy:
|
||||||
|
false = Types.booleanType(0)
|
||||||
|
true = Types.booleanType(1)
|
||||||
|
structType = Types.structType
|
||||||
|
faultType = Types.faultType
|
||||||
|
else:
|
||||||
|
false = SOAP.booleanType(0)
|
||||||
|
true = SOAP.booleanType(1)
|
||||||
|
structType = SOAP.structType
|
||||||
|
faultType = SOAP.faultType
|
||||||
|
|
||||||
|
#
|
||||||
|
# Get a SOAP Proxy object in the correct way for the module we're using
|
||||||
|
#
|
||||||
|
def getProxy( url, namespace, http_proxy ):
|
||||||
|
if SOAPpy:
|
||||||
|
return SOAPProxy( url,
|
||||||
|
namespace = namespace,
|
||||||
|
http_proxy = http_proxy )
|
||||||
|
|
||||||
|
else:
|
||||||
|
return SOAP.SOAPProxy( url,
|
||||||
|
namespace = namespace,
|
||||||
|
http_proxy = http_proxy )
|
||||||
|
|
||||||
|
#
|
||||||
|
# Convert an object to a dictionary in the proper way for the module
|
||||||
|
# we're using for SOAP
|
||||||
|
#
|
||||||
|
def toDict( obj ):
|
||||||
|
if SOAPpy:
|
||||||
|
return obj._asdict()
|
||||||
|
else:
|
||||||
|
return obj._asdict
|
||||||
478
others/SOAPpy/Client.py
Normal file
478
others/SOAPpy/Client.py
Normal file
@ -0,0 +1,478 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
#
|
||||||
|
# SOAPpy - Cayce Ullman (cayce@actzero.com)
|
||||||
|
# Brian Matthews (blm@actzero.com)
|
||||||
|
# Gregory Warnes (gregory_r_warnes@groton.pfizer.com)
|
||||||
|
# Christopher Blunck (blunck@gst.com)
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from __future__ import nested_scopes
|
||||||
|
|
||||||
|
#import xml.sax
|
||||||
|
import urllib
|
||||||
|
from types import *
|
||||||
|
import re
|
||||||
|
import base64
|
||||||
|
|
||||||
|
# SOAPpy modules
|
||||||
|
from Errors import *
|
||||||
|
from Config import Config
|
||||||
|
from Parser import parseSOAPRPC
|
||||||
|
from SOAPBuilder import buildSOAP
|
||||||
|
from Utilities import *
|
||||||
|
from Types import faultType, simplify
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Client
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
|
||||||
|
def SOAPUserAgent():
|
||||||
|
return "SOAPpy " + __version__ + " (pywebsvcs.sf.net)"
|
||||||
|
|
||||||
|
|
||||||
|
class SOAPAddress:
|
||||||
|
def __init__(self, url, config = Config):
|
||||||
|
proto, uri = urllib.splittype(url)
|
||||||
|
|
||||||
|
# apply some defaults
|
||||||
|
if uri[0:2] != '//':
|
||||||
|
if proto != None:
|
||||||
|
uri = proto + ':' + uri
|
||||||
|
|
||||||
|
uri = '//' + uri
|
||||||
|
proto = 'http'
|
||||||
|
|
||||||
|
host, path = urllib.splithost(uri)
|
||||||
|
|
||||||
|
try:
|
||||||
|
int(host)
|
||||||
|
host = 'localhost:' + host
|
||||||
|
except:
|
||||||
|
pass
|
||||||
|
|
||||||
|
if not path:
|
||||||
|
path = '/'
|
||||||
|
|
||||||
|
if proto not in ('http', 'https', 'httpg'):
|
||||||
|
raise IOError, "unsupported SOAP protocol"
|
||||||
|
if proto == 'httpg' and not config.GSIclient:
|
||||||
|
raise AttributeError, \
|
||||||
|
"GSI client not supported by this Python installation"
|
||||||
|
if proto == 'https' and not config.SSLclient:
|
||||||
|
raise AttributeError, \
|
||||||
|
"SSL client not supported by this Python installation"
|
||||||
|
|
||||||
|
self.user,host = urllib.splituser(host)
|
||||||
|
self.proto = proto
|
||||||
|
self.host = host
|
||||||
|
self.path = path
|
||||||
|
|
||||||
|
def __str__(self):
|
||||||
|
return "%(proto)s://%(host)s%(path)s" % self.__dict__
|
||||||
|
|
||||||
|
__repr__ = __str__
|
||||||
|
|
||||||
|
|
||||||
|
class HTTPTransport:
|
||||||
|
def getNS(self, original_namespace, data):
|
||||||
|
"""Extract the (possibly extended) namespace from the returned
|
||||||
|
SOAP message."""
|
||||||
|
|
||||||
|
if type(original_namespace) == StringType:
|
||||||
|
pattern="xmlns:\w+=['\"](" + original_namespace + "[^'\"]*)['\"]"
|
||||||
|
match = re.search(pattern, data)
|
||||||
|
if match:
|
||||||
|
return match.group(1)
|
||||||
|
else:
|
||||||
|
return original_namespace
|
||||||
|
else:
|
||||||
|
return original_namespace
|
||||||
|
|
||||||
|
# Need a Timeout someday?
|
||||||
|
def call(self, addr, data, namespace, soapaction = None, encoding = None,
|
||||||
|
http_proxy = None, config = Config):
|
||||||
|
|
||||||
|
import httplib
|
||||||
|
|
||||||
|
if not isinstance(addr, SOAPAddress):
|
||||||
|
addr = SOAPAddress(addr, config)
|
||||||
|
|
||||||
|
# Build a request
|
||||||
|
if http_proxy:
|
||||||
|
real_addr = http_proxy
|
||||||
|
real_path = addr.proto + "://" + addr.host + addr.path
|
||||||
|
else:
|
||||||
|
real_addr = addr.host
|
||||||
|
real_path = addr.path
|
||||||
|
|
||||||
|
if addr.proto == 'httpg':
|
||||||
|
from pyGlobus.io import GSIHTTP
|
||||||
|
r = GSIHTTP(real_addr, tcpAttr = config.tcpAttr)
|
||||||
|
elif addr.proto == 'https':
|
||||||
|
r = httplib.HTTPS(real_addr)
|
||||||
|
else:
|
||||||
|
r = httplib.HTTP(real_addr)
|
||||||
|
|
||||||
|
r.putrequest("POST", real_path)
|
||||||
|
|
||||||
|
r.putheader("Host", addr.host)
|
||||||
|
r.putheader("User-agent", SOAPUserAgent())
|
||||||
|
t = 'text/xml';
|
||||||
|
if encoding != None:
|
||||||
|
t += '; charset="%s"' % encoding
|
||||||
|
r.putheader("Content-type", t)
|
||||||
|
r.putheader("Content-length", str(len(data)))
|
||||||
|
|
||||||
|
# if user is not a user:passwd format
|
||||||
|
# we'll receive a failure from the server. . .I guess (??)
|
||||||
|
if addr.user != None:
|
||||||
|
val = base64.encodestring(addr.user)
|
||||||
|
r.putheader('Authorization','Basic ' + val.replace('\012',''))
|
||||||
|
|
||||||
|
# This fixes sending either "" or "None"
|
||||||
|
if soapaction == None or len(soapaction) == 0:
|
||||||
|
r.putheader("SOAPAction", "")
|
||||||
|
else:
|
||||||
|
r.putheader("SOAPAction", '"%s"' % soapaction)
|
||||||
|
|
||||||
|
if config.dumpHeadersOut:
|
||||||
|
s = 'Outgoing HTTP headers'
|
||||||
|
debugHeader(s)
|
||||||
|
print "POST %s %s" % (real_path, r._http_vsn_str)
|
||||||
|
print "Host:", addr.host
|
||||||
|
print "User-agent: SOAPpy " + __version__ + " (http://pywebsvcs.sf.net)"
|
||||||
|
print "Content-type:", t
|
||||||
|
print "Content-length:", len(data)
|
||||||
|
print 'SOAPAction: "%s"' % soapaction
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
r.endheaders()
|
||||||
|
|
||||||
|
if config.dumpSOAPOut:
|
||||||
|
s = 'Outgoing SOAP'
|
||||||
|
debugHeader(s)
|
||||||
|
print data,
|
||||||
|
if data[-1] != '\n':
|
||||||
|
print
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
# send the payload
|
||||||
|
r.send(data)
|
||||||
|
|
||||||
|
# read response line
|
||||||
|
code, msg, headers = r.getreply()
|
||||||
|
|
||||||
|
content_type = headers.get("content-type","text/xml")
|
||||||
|
content_length = headers.get("Content-length")
|
||||||
|
if content_length == None:
|
||||||
|
# No Content-Length provided; just read the whole socket
|
||||||
|
# This won't work with HTTP/1.1 chunked encoding
|
||||||
|
data = r.getfile().read()
|
||||||
|
message_len = len(data)
|
||||||
|
else:
|
||||||
|
message_len = int(content_length)
|
||||||
|
data = r.getfile().read(message_len)
|
||||||
|
|
||||||
|
if(config.debug):
|
||||||
|
print "code=",code
|
||||||
|
print "msg=", msg
|
||||||
|
print "headers=", headers
|
||||||
|
print "content-type=", content_type
|
||||||
|
print "data=", data
|
||||||
|
|
||||||
|
if config.dumpHeadersIn:
|
||||||
|
s = 'Incoming HTTP headers'
|
||||||
|
debugHeader(s)
|
||||||
|
if headers.headers:
|
||||||
|
print "HTTP/1.? %d %s" % (code, msg)
|
||||||
|
print "\n".join(map (lambda x: x.strip(), headers.headers))
|
||||||
|
else:
|
||||||
|
print "HTTP/0.9 %d %s" % (code, msg)
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
def startswith(string, val):
|
||||||
|
return string[0:len(val)] == val
|
||||||
|
|
||||||
|
if code == 500 and not \
|
||||||
|
( startswith(content_type, "text/xml") and message_len > 0 ):
|
||||||
|
raise HTTPError(code, msg)
|
||||||
|
|
||||||
|
if config.dumpSOAPIn:
|
||||||
|
s = 'Incoming SOAP'
|
||||||
|
debugHeader(s)
|
||||||
|
print data,
|
||||||
|
if (len(data)>0) and (data[-1] != '\n'):
|
||||||
|
print
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
if code not in (200, 500):
|
||||||
|
raise HTTPError(code, msg)
|
||||||
|
|
||||||
|
|
||||||
|
# get the new namespace
|
||||||
|
if namespace is None:
|
||||||
|
new_ns = None
|
||||||
|
else:
|
||||||
|
new_ns = self.getNS(namespace, data)
|
||||||
|
|
||||||
|
# return response payload
|
||||||
|
return data, new_ns
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# SOAP Proxy
|
||||||
|
################################################################################
|
||||||
|
class SOAPProxy:
|
||||||
|
def __init__(self, proxy, namespace = None, soapaction = None,
|
||||||
|
header = None, methodattrs = None, transport = HTTPTransport,
|
||||||
|
encoding = 'UTF-8', throw_faults = 1, unwrap_results = None,
|
||||||
|
http_proxy=None, config = Config, noroot = 0,
|
||||||
|
simplify_objects=None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
# get default values for unwrap_results and simplify_objects
|
||||||
|
# from config
|
||||||
|
if unwrap_results is None:
|
||||||
|
self.unwrap_results=config.unwrap_results
|
||||||
|
else:
|
||||||
|
self.unwrap_results=unwrap_results
|
||||||
|
|
||||||
|
if simplify_objects is None:
|
||||||
|
self.simplify_objects=config.simplify_objects
|
||||||
|
else:
|
||||||
|
self.simplify_objects=simplify_objects
|
||||||
|
|
||||||
|
self.proxy = SOAPAddress(proxy, config)
|
||||||
|
self.namespace = namespace
|
||||||
|
self.soapaction = soapaction
|
||||||
|
self.header = header
|
||||||
|
self.methodattrs = methodattrs
|
||||||
|
self.transport = transport()
|
||||||
|
self.encoding = encoding
|
||||||
|
self.throw_faults = throw_faults
|
||||||
|
self.http_proxy = http_proxy
|
||||||
|
self.config = config
|
||||||
|
self.noroot = noroot
|
||||||
|
|
||||||
|
# GSI Additions
|
||||||
|
if hasattr(config, "channel_mode") and \
|
||||||
|
hasattr(config, "delegation_mode"):
|
||||||
|
self.channel_mode = config.channel_mode
|
||||||
|
self.delegation_mode = config.delegation_mode
|
||||||
|
#end GSI Additions
|
||||||
|
|
||||||
|
def invoke(self, method, args):
|
||||||
|
return self.__call(method, args, {})
|
||||||
|
|
||||||
|
def __call(self, name, args, kw, ns = None, sa = None, hd = None,
|
||||||
|
ma = None):
|
||||||
|
|
||||||
|
ns = ns or self.namespace
|
||||||
|
ma = ma or self.methodattrs
|
||||||
|
|
||||||
|
if sa: # Get soapaction
|
||||||
|
if type(sa) == TupleType:
|
||||||
|
sa = sa[0]
|
||||||
|
else:
|
||||||
|
if self.soapaction:
|
||||||
|
sa = self.soapaction
|
||||||
|
else:
|
||||||
|
sa = name
|
||||||
|
|
||||||
|
if hd: # Get header
|
||||||
|
if type(hd) == TupleType:
|
||||||
|
hd = hd[0]
|
||||||
|
else:
|
||||||
|
hd = self.header
|
||||||
|
|
||||||
|
hd = hd or self.header
|
||||||
|
|
||||||
|
if ma: # Get methodattrs
|
||||||
|
if type(ma) == TupleType: ma = ma[0]
|
||||||
|
else:
|
||||||
|
ma = self.methodattrs
|
||||||
|
ma = ma or self.methodattrs
|
||||||
|
|
||||||
|
m = buildSOAP(args = args, kw = kw, method = name, namespace = ns,
|
||||||
|
header = hd, methodattrs = ma, encoding = self.encoding,
|
||||||
|
config = self.config, noroot = self.noroot)
|
||||||
|
|
||||||
|
|
||||||
|
call_retry = 0
|
||||||
|
try:
|
||||||
|
|
||||||
|
r, self.namespace = self.transport.call(self.proxy, m, ns, sa,
|
||||||
|
encoding = self.encoding,
|
||||||
|
http_proxy = self.http_proxy,
|
||||||
|
config = self.config)
|
||||||
|
|
||||||
|
except Exception, ex:
|
||||||
|
#
|
||||||
|
# Call failed.
|
||||||
|
#
|
||||||
|
# See if we have a fault handling vector installed in our
|
||||||
|
# config. If we do, invoke it. If it returns a true value,
|
||||||
|
# retry the call.
|
||||||
|
#
|
||||||
|
# In any circumstance other than the fault handler returning
|
||||||
|
# true, reraise the exception. This keeps the semantics of this
|
||||||
|
# code the same as without the faultHandler code.
|
||||||
|
#
|
||||||
|
|
||||||
|
if hasattr(self.config, "faultHandler"):
|
||||||
|
if callable(self.config.faultHandler):
|
||||||
|
call_retry = self.config.faultHandler(self.proxy, ex)
|
||||||
|
if not call_retry:
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
raise
|
||||||
|
|
||||||
|
if call_retry:
|
||||||
|
r, self.namespace = self.transport.call(self.proxy, m, ns, sa,
|
||||||
|
encoding = self.encoding,
|
||||||
|
http_proxy = self.http_proxy,
|
||||||
|
config = self.config)
|
||||||
|
|
||||||
|
|
||||||
|
p, attrs = parseSOAPRPC(r, attrs = 1)
|
||||||
|
|
||||||
|
try:
|
||||||
|
throw_struct = self.throw_faults and \
|
||||||
|
isinstance (p, faultType)
|
||||||
|
except:
|
||||||
|
throw_struct = 0
|
||||||
|
|
||||||
|
if throw_struct:
|
||||||
|
#print p
|
||||||
|
raise p
|
||||||
|
|
||||||
|
# If unwrap_results=1 and there is only element in the struct,
|
||||||
|
# SOAPProxy will assume that this element is the result
|
||||||
|
# and return it rather than the struct containing it.
|
||||||
|
# Otherwise SOAPproxy will return the struct with all the
|
||||||
|
# elements as attributes.
|
||||||
|
if self.unwrap_results:
|
||||||
|
try:
|
||||||
|
count = 0
|
||||||
|
for i in p.__dict__.keys():
|
||||||
|
if i[0] != "_": # don't count the private stuff
|
||||||
|
count += 1
|
||||||
|
t = getattr(p, i)
|
||||||
|
if count == 1: # Only one piece of data, bubble it up
|
||||||
|
p = t
|
||||||
|
except:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Automatically simplfy SOAP complex types into the
|
||||||
|
# corresponding python types. (structType --> dict,
|
||||||
|
# arrayType --> array, etc.)
|
||||||
|
if self.simplify_objects:
|
||||||
|
p = simplify(p)
|
||||||
|
|
||||||
|
if self.config.returnAllAttrs:
|
||||||
|
return p, attrs
|
||||||
|
return p
|
||||||
|
|
||||||
|
def _callWithBody(self, body):
|
||||||
|
return self.__call(None, body, {})
|
||||||
|
|
||||||
|
def __getattr__(self, name): # hook to catch method calls
|
||||||
|
if name == '__del__':
|
||||||
|
raise AttributeError, name
|
||||||
|
return self.__Method(self.__call, name, config = self.config)
|
||||||
|
|
||||||
|
# To handle attribute wierdness
|
||||||
|
class __Method:
|
||||||
|
# Some magic to bind a SOAP method to an RPC server.
|
||||||
|
# Supports "nested" methods (e.g. examples.getStateName) -- concept
|
||||||
|
# borrowed from xmlrpc/soaplib -- www.pythonware.com
|
||||||
|
# Altered (improved?) to let you inline namespaces on a per call
|
||||||
|
# basis ala SOAP::LITE -- www.soaplite.com
|
||||||
|
|
||||||
|
def __init__(self, call, name, ns = None, sa = None, hd = None,
|
||||||
|
ma = None, config = Config):
|
||||||
|
|
||||||
|
self.__call = call
|
||||||
|
self.__name = name
|
||||||
|
self.__ns = ns
|
||||||
|
self.__sa = sa
|
||||||
|
self.__hd = hd
|
||||||
|
self.__ma = ma
|
||||||
|
self.__config = config
|
||||||
|
return
|
||||||
|
|
||||||
|
def __call__(self, *args, **kw):
|
||||||
|
if self.__name[0] == "_":
|
||||||
|
if self.__name in ["__repr__","__str__"]:
|
||||||
|
return self.__repr__()
|
||||||
|
else:
|
||||||
|
return self.__f_call(*args, **kw)
|
||||||
|
else:
|
||||||
|
return self.__r_call(*args, **kw)
|
||||||
|
|
||||||
|
def __getattr__(self, name):
|
||||||
|
if name == '__del__':
|
||||||
|
raise AttributeError, name
|
||||||
|
if self.__name[0] == "_":
|
||||||
|
# Don't nest method if it is a directive
|
||||||
|
return self.__class__(self.__call, name, self.__ns,
|
||||||
|
self.__sa, self.__hd, self.__ma)
|
||||||
|
|
||||||
|
return self.__class__(self.__call, "%s.%s" % (self.__name, name),
|
||||||
|
self.__ns, self.__sa, self.__hd, self.__ma)
|
||||||
|
|
||||||
|
def __f_call(self, *args, **kw):
|
||||||
|
if self.__name == "_ns": self.__ns = args
|
||||||
|
elif self.__name == "_sa": self.__sa = args
|
||||||
|
elif self.__name == "_hd": self.__hd = args
|
||||||
|
elif self.__name == "_ma": self.__ma = args
|
||||||
|
return self
|
||||||
|
|
||||||
|
def __r_call(self, *args, **kw):
|
||||||
|
return self.__call(self.__name, args, kw, self.__ns, self.__sa,
|
||||||
|
self.__hd, self.__ma)
|
||||||
|
|
||||||
|
def __repr__(self):
|
||||||
|
return "<%s at %d>" % (self.__class__, id(self))
|
||||||
202
others/SOAPpy/Config.py
Normal file
202
others/SOAPpy/Config.py
Normal file
@ -0,0 +1,202 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
import copy, socket
|
||||||
|
from types import *
|
||||||
|
|
||||||
|
from NS import NS
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Configuration class
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
class SOAPConfig:
|
||||||
|
__readonly = ('SSLserver', 'SSLclient', 'GSIserver', 'GSIclient')
|
||||||
|
|
||||||
|
def __init__(self, config = None, **kw):
|
||||||
|
d = self.__dict__
|
||||||
|
|
||||||
|
if config:
|
||||||
|
if not isinstance(config, SOAPConfig):
|
||||||
|
raise AttributeError, \
|
||||||
|
"initializer must be SOAPConfig instance"
|
||||||
|
|
||||||
|
s = config.__dict__
|
||||||
|
|
||||||
|
for k, v in s.items():
|
||||||
|
if k[0] != '_':
|
||||||
|
d[k] = v
|
||||||
|
else:
|
||||||
|
# Setting debug also sets returnFaultInfo,
|
||||||
|
# dumpHeadersIn, dumpHeadersOut, dumpSOAPIn, and dumpSOAPOut
|
||||||
|
self.debug = 0
|
||||||
|
self.dumpFaultInfo = 0
|
||||||
|
# Setting namespaceStyle sets typesNamespace, typesNamespaceURI,
|
||||||
|
# schemaNamespace, and schemaNamespaceURI
|
||||||
|
self.namespaceStyle = '1999'
|
||||||
|
self.strictNamespaces = 0
|
||||||
|
self.typed = 1
|
||||||
|
self.buildWithNamespacePrefix = 1
|
||||||
|
self.returnAllAttrs = 0
|
||||||
|
|
||||||
|
# Strict checking of range for floats and doubles
|
||||||
|
self.strict_range = 0
|
||||||
|
|
||||||
|
# Default encoding for dictionary keys
|
||||||
|
self.dict_encoding = 'ascii'
|
||||||
|
|
||||||
|
# New argument name handling mechanism. See
|
||||||
|
# README.MethodParameterNaming for details
|
||||||
|
self.specialArgs = 1
|
||||||
|
|
||||||
|
# If unwrap_results=1 and there is only element in the struct,
|
||||||
|
# SOAPProxy will assume that this element is the result
|
||||||
|
# and return it rather than the struct containing it.
|
||||||
|
# Otherwise SOAPproxy will return the struct with all the
|
||||||
|
# elements as attributes.
|
||||||
|
self.unwrap_results = 1
|
||||||
|
|
||||||
|
# Automatically convert SOAP complex types, and
|
||||||
|
# (recursively) public contents into the corresponding
|
||||||
|
# python types. (Private subobjects have names that start
|
||||||
|
# with '_'.)
|
||||||
|
#
|
||||||
|
# Conversions:
|
||||||
|
# - faultType --> raise python exception
|
||||||
|
# - arrayType --> array
|
||||||
|
# - compoundType --> dictionary
|
||||||
|
#
|
||||||
|
self.simplify_objects = 0
|
||||||
|
|
||||||
|
# Per-class authorization method. If this is set, before
|
||||||
|
# calling a any class method, the specified authorization
|
||||||
|
# method will be called. If it returns 1, the method call
|
||||||
|
# will proceed, otherwise the call will throw with an
|
||||||
|
# authorization error.
|
||||||
|
self.authMethod = None
|
||||||
|
|
||||||
|
# Globus Support if pyGlobus.io available
|
||||||
|
try:
|
||||||
|
from pyGlobus import io;
|
||||||
|
d['GSIserver'] = 1
|
||||||
|
d['GSIclient'] = 1
|
||||||
|
except:
|
||||||
|
d['GSIserver'] = 0
|
||||||
|
d['GSIclient'] = 0
|
||||||
|
|
||||||
|
|
||||||
|
# Server SSL support if M2Crypto.SSL available
|
||||||
|
try:
|
||||||
|
from M2Crypto import SSL
|
||||||
|
d['SSLserver'] = 1
|
||||||
|
except:
|
||||||
|
d['SSLserver'] = 0
|
||||||
|
|
||||||
|
# Client SSL support if socket.ssl available
|
||||||
|
try:
|
||||||
|
from socket import ssl
|
||||||
|
d['SSLclient'] = 1
|
||||||
|
except:
|
||||||
|
d['SSLclient'] = 0
|
||||||
|
|
||||||
|
for k, v in kw.items():
|
||||||
|
if k[0] != '_':
|
||||||
|
setattr(self, k, v)
|
||||||
|
|
||||||
|
def __setattr__(self, name, value):
|
||||||
|
if name in self.__readonly:
|
||||||
|
raise AttributeError, "readonly configuration setting"
|
||||||
|
|
||||||
|
d = self.__dict__
|
||||||
|
|
||||||
|
if name in ('typesNamespace', 'typesNamespaceURI',
|
||||||
|
'schemaNamespace', 'schemaNamespaceURI'):
|
||||||
|
|
||||||
|
if name[-3:] == 'URI':
|
||||||
|
base, uri = name[:-3], 1
|
||||||
|
else:
|
||||||
|
base, uri = name, 0
|
||||||
|
|
||||||
|
if type(value) == StringType:
|
||||||
|
if NS.NSMAP.has_key(value):
|
||||||
|
n = (value, NS.NSMAP[value])
|
||||||
|
elif NS.NSMAP_R.has_key(value):
|
||||||
|
n = (NS.NSMAP_R[value], value)
|
||||||
|
else:
|
||||||
|
raise AttributeError, "unknown namespace"
|
||||||
|
elif type(value) in (ListType, TupleType):
|
||||||
|
if uri:
|
||||||
|
n = (value[1], value[0])
|
||||||
|
else:
|
||||||
|
n = (value[0], value[1])
|
||||||
|
else:
|
||||||
|
raise AttributeError, "unknown namespace type"
|
||||||
|
|
||||||
|
d[base], d[base + 'URI'] = n
|
||||||
|
|
||||||
|
try:
|
||||||
|
d['namespaceStyle'] = \
|
||||||
|
NS.STMAP_R[(d['typesNamespace'], d['schemaNamespace'])]
|
||||||
|
except:
|
||||||
|
d['namespaceStyle'] = ''
|
||||||
|
|
||||||
|
elif name == 'namespaceStyle':
|
||||||
|
value = str(value)
|
||||||
|
|
||||||
|
if not NS.STMAP.has_key(value):
|
||||||
|
raise AttributeError, "unknown namespace style"
|
||||||
|
|
||||||
|
d[name] = value
|
||||||
|
n = d['typesNamespace'] = NS.STMAP[value][0]
|
||||||
|
d['typesNamespaceURI'] = NS.NSMAP[n]
|
||||||
|
n = d['schemaNamespace'] = NS.STMAP[value][1]
|
||||||
|
d['schemaNamespaceURI'] = NS.NSMAP[n]
|
||||||
|
|
||||||
|
elif name == 'debug':
|
||||||
|
d[name] = \
|
||||||
|
d['returnFaultInfo'] = \
|
||||||
|
d['dumpHeadersIn'] = \
|
||||||
|
d['dumpHeadersOut'] = \
|
||||||
|
d['dumpSOAPIn'] = \
|
||||||
|
d['dumpSOAPOut'] = value
|
||||||
|
|
||||||
|
else:
|
||||||
|
d[name] = value
|
||||||
|
|
||||||
|
|
||||||
|
Config = SOAPConfig()
|
||||||
79
others/SOAPpy/Errors.py
Normal file
79
others/SOAPpy/Errors.py
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
#
|
||||||
|
# SOAPpy - Cayce Ullman (cayce@actzero.com)
|
||||||
|
# Brian Matthews (blm@actzero.com)
|
||||||
|
# Gregory Warnes (gregory_r_warnes@groton.pfizer.com)
|
||||||
|
# Christopher Blunck (blunck@gst.com)
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
import exceptions
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Exceptions
|
||||||
|
################################################################################
|
||||||
|
class Error(exceptions.Exception):
|
||||||
|
def __init__(self, msg):
|
||||||
|
self.msg = msg
|
||||||
|
def __str__(self):
|
||||||
|
return "<Error : %s>" % self.msg
|
||||||
|
__repr__ = __str__
|
||||||
|
def __call__(self):
|
||||||
|
return (msg,)
|
||||||
|
|
||||||
|
class RecursionError(Error):
|
||||||
|
pass
|
||||||
|
|
||||||
|
class UnknownTypeError(Error):
|
||||||
|
pass
|
||||||
|
|
||||||
|
class HTTPError(Error):
|
||||||
|
# indicates an HTTP protocol error
|
||||||
|
def __init__(self, code, msg):
|
||||||
|
self.code = code
|
||||||
|
self.msg = msg
|
||||||
|
def __str__(self):
|
||||||
|
return "<HTTPError %s %s>" % (self.code, self.msg)
|
||||||
|
__repr__ = __str__
|
||||||
|
def __call___(self):
|
||||||
|
return (self.code, self.msg, )
|
||||||
|
|
||||||
|
class UnderflowError(exceptions.ArithmeticError):
|
||||||
|
pass
|
||||||
|
|
||||||
143
others/SOAPpy/GSIServer.py
Normal file
143
others/SOAPpy/GSIServer.py
Normal file
@ -0,0 +1,143 @@
|
|||||||
|
"""
|
||||||
|
GSIServer - Contributed by Ivan R. Judson <judson@mcs.anl.gov>
|
||||||
|
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
#
|
||||||
|
# SOAPpy - Cayce Ullman (cayce@actzero.com)
|
||||||
|
# Brian Matthews (blm@actzero.com)
|
||||||
|
# Gregory Warnes (gregory_r_warnes@groton.pfizer.com)
|
||||||
|
# Christopher Blunck (blunck@gst.com)
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from __future__ import nested_scopes
|
||||||
|
|
||||||
|
#import xml.sax
|
||||||
|
import re
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
import SocketServer
|
||||||
|
from types import *
|
||||||
|
import BaseHTTPServer
|
||||||
|
|
||||||
|
# SOAPpy modules
|
||||||
|
from Parser import parseSOAPRPC
|
||||||
|
from Config import SOAPConfig
|
||||||
|
from Types import faultType, voidType, simplify
|
||||||
|
from NS import NS
|
||||||
|
from SOAPBuilder import buildSOAP
|
||||||
|
from Utilities import debugHeader, debugFooter
|
||||||
|
|
||||||
|
try: from M2Crypto import SSL
|
||||||
|
except: pass
|
||||||
|
|
||||||
|
#####
|
||||||
|
|
||||||
|
from Server import *
|
||||||
|
|
||||||
|
from pyGlobus.io import GSITCPSocketServer, ThreadingGSITCPSocketServer
|
||||||
|
from pyGlobus import ioc
|
||||||
|
|
||||||
|
def GSIConfig():
|
||||||
|
config = SOAPConfig()
|
||||||
|
config.channel_mode = ioc.GLOBUS_IO_SECURE_CHANNEL_MODE_GSI_WRAP
|
||||||
|
config.delegation_mode = ioc.GLOBUS_IO_SECURE_DELEGATION_MODE_FULL_PROXY
|
||||||
|
config.tcpAttr = None
|
||||||
|
config.authMethod = "_authorize"
|
||||||
|
return config
|
||||||
|
|
||||||
|
Config = GSIConfig()
|
||||||
|
|
||||||
|
class GSISOAPServer(GSITCPSocketServer, SOAPServerBase):
|
||||||
|
def __init__(self, addr = ('localhost', 8000),
|
||||||
|
RequestHandler = SOAPRequestHandler, log = 0,
|
||||||
|
encoding = 'UTF-8', config = Config, namespace = None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
self.namespace = namespace
|
||||||
|
self.objmap = {}
|
||||||
|
self.funcmap = {}
|
||||||
|
self.encoding = encoding
|
||||||
|
self.config = config
|
||||||
|
self.log = log
|
||||||
|
|
||||||
|
self.allow_reuse_address= 1
|
||||||
|
|
||||||
|
GSITCPSocketServer.__init__(self, addr, RequestHandler,
|
||||||
|
self.config.channel_mode,
|
||||||
|
self.config.delegation_mode,
|
||||||
|
tcpAttr = self.config.tcpAttr)
|
||||||
|
|
||||||
|
def get_request(self):
|
||||||
|
sock, addr = GSITCPSocketServer.get_request(self)
|
||||||
|
|
||||||
|
return sock, addr
|
||||||
|
|
||||||
|
class ThreadingGSISOAPServer(ThreadingGSITCPSocketServer, SOAPServerBase):
|
||||||
|
|
||||||
|
def __init__(self, addr = ('localhost', 8000),
|
||||||
|
RequestHandler = SOAPRequestHandler, log = 0,
|
||||||
|
encoding = 'UTF-8', config = Config, namespace = None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
self.namespace = namespace
|
||||||
|
self.objmap = {}
|
||||||
|
self.funcmap = {}
|
||||||
|
self.encoding = encoding
|
||||||
|
self.config = config
|
||||||
|
self.log = log
|
||||||
|
|
||||||
|
self.allow_reuse_address= 1
|
||||||
|
|
||||||
|
ThreadingGSITCPSocketServer.__init__(self, addr, RequestHandler,
|
||||||
|
self.config.channel_mode,
|
||||||
|
self.config.delegation_mode,
|
||||||
|
tcpAttr = self.config.tcpAttr)
|
||||||
|
|
||||||
|
def get_request(self):
|
||||||
|
sock, addr = ThreadingGSITCPSocketServer.get_request(self)
|
||||||
|
|
||||||
|
return sock, addr
|
||||||
|
|
||||||
104
others/SOAPpy/NS.py
Normal file
104
others/SOAPpy/NS.py
Normal file
@ -0,0 +1,104 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
#
|
||||||
|
# SOAPpy - Cayce Ullman (cayce@actzero.com)
|
||||||
|
# Brian Matthews (blm@actzero.com)
|
||||||
|
# Gregory Warnes (gregory_r_warnes@groton.pfizer.com)
|
||||||
|
# Christopher Blunck (blunck@gst.com)
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import nested_scopes
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
##############################################################################
|
||||||
|
# Namespace Class
|
||||||
|
################################################################################
|
||||||
|
def invertDict(dict):
|
||||||
|
d = {}
|
||||||
|
|
||||||
|
for k, v in dict.items():
|
||||||
|
d[v] = k
|
||||||
|
|
||||||
|
return d
|
||||||
|
|
||||||
|
class NS:
|
||||||
|
XML = "http://www.w3.org/XML/1998/namespace"
|
||||||
|
|
||||||
|
ENV = "http://schemas.xmlsoap.org/soap/envelope/"
|
||||||
|
ENC = "http://schemas.xmlsoap.org/soap/encoding/"
|
||||||
|
|
||||||
|
XSD = "http://www.w3.org/1999/XMLSchema"
|
||||||
|
XSD2 = "http://www.w3.org/2000/10/XMLSchema"
|
||||||
|
XSD3 = "http://www.w3.org/2001/XMLSchema"
|
||||||
|
|
||||||
|
XSD_L = [XSD, XSD2, XSD3]
|
||||||
|
EXSD_L= [ENC, XSD, XSD2, XSD3]
|
||||||
|
|
||||||
|
XSI = "http://www.w3.org/1999/XMLSchema-instance"
|
||||||
|
XSI2 = "http://www.w3.org/2000/10/XMLSchema-instance"
|
||||||
|
XSI3 = "http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
XSI_L = [XSI, XSI2, XSI3]
|
||||||
|
|
||||||
|
URN = "http://soapinterop.org/xsd"
|
||||||
|
|
||||||
|
# For generated messages
|
||||||
|
XML_T = "xml"
|
||||||
|
ENV_T = "SOAP-ENV"
|
||||||
|
ENC_T = "SOAP-ENC"
|
||||||
|
XSD_T = "xsd"
|
||||||
|
XSD2_T= "xsd2"
|
||||||
|
XSD3_T= "xsd3"
|
||||||
|
XSI_T = "xsi"
|
||||||
|
XSI2_T= "xsi2"
|
||||||
|
XSI3_T= "xsi3"
|
||||||
|
URN_T = "urn"
|
||||||
|
|
||||||
|
NSMAP = {ENV_T: ENV, ENC_T: ENC, XSD_T: XSD, XSD2_T: XSD2,
|
||||||
|
XSD3_T: XSD3, XSI_T: XSI, XSI2_T: XSI2, XSI3_T: XSI3,
|
||||||
|
URN_T: URN}
|
||||||
|
NSMAP_R = invertDict(NSMAP)
|
||||||
|
|
||||||
|
STMAP = {'1999': (XSD_T, XSI_T), '2000': (XSD2_T, XSI2_T),
|
||||||
|
'2001': (XSD3_T, XSI3_T)}
|
||||||
|
STMAP_R = invertDict(STMAP)
|
||||||
|
|
||||||
|
def __init__(self):
|
||||||
|
raise Error, "Don't instantiate this"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
1024
others/SOAPpy/Parser.py
Normal file
1024
others/SOAPpy/Parser.py
Normal file
File diff suppressed because it is too large
Load Diff
40
others/SOAPpy/SOAP.py
Normal file
40
others/SOAPpy/SOAP.py
Normal file
@ -0,0 +1,40 @@
|
|||||||
|
"""This file is here for backward compatibility with versions <= 0.9.9
|
||||||
|
|
||||||
|
Delete when 1.0.0 is released!
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from Client import *
|
||||||
|
from Config import *
|
||||||
|
from Errors import *
|
||||||
|
from NS import *
|
||||||
|
from Parser import *
|
||||||
|
from SOAPBuilder import *
|
||||||
|
from Server import *
|
||||||
|
from Types import *
|
||||||
|
from Utilities import *
|
||||||
|
import wstools
|
||||||
|
import WSDL
|
||||||
|
|
||||||
|
from warnings import warn
|
||||||
|
|
||||||
|
warn("""
|
||||||
|
|
||||||
|
The sub-module SOAPpy.SOAP is deprecated and is only
|
||||||
|
provided for short-term backward compatibility. Objects are now
|
||||||
|
available directly within the SOAPpy module. Thus, instead of
|
||||||
|
|
||||||
|
from SOAPpy import SOAP
|
||||||
|
...
|
||||||
|
SOAP.SOAPProxy(...)
|
||||||
|
|
||||||
|
use
|
||||||
|
|
||||||
|
from SOAPpy import SOAPProxy
|
||||||
|
...
|
||||||
|
SOAPProxy(...)
|
||||||
|
|
||||||
|
instead.
|
||||||
|
""", DeprecationWarning)
|
||||||
620
others/SOAPpy/SOAPBuilder.py
Normal file
620
others/SOAPpy/SOAPBuilder.py
Normal file
@ -0,0 +1,620 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
import cgi
|
||||||
|
import copy
|
||||||
|
from wstools.XMLname import toXMLname, fromXMLname
|
||||||
|
import fpconst
|
||||||
|
|
||||||
|
# SOAPpy modules
|
||||||
|
from Config import Config
|
||||||
|
from NS import NS
|
||||||
|
from Types import *
|
||||||
|
|
||||||
|
# Test whether this Python version has Types.BooleanType
|
||||||
|
# If it doesn't have it, then False and True are serialized as integers
|
||||||
|
try:
|
||||||
|
BooleanType
|
||||||
|
pythonHasBooleanType = 1
|
||||||
|
except NameError:
|
||||||
|
pythonHasBooleanType = 0
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# SOAP Builder
|
||||||
|
################################################################################
|
||||||
|
class SOAPBuilder:
|
||||||
|
_xml_top = '<?xml version="1.0"?>\n'
|
||||||
|
_xml_enc_top = '<?xml version="1.0" encoding="%s"?>\n'
|
||||||
|
_env_top = '%(ENV_T)s:Envelope %(ENV_T)s:encodingStyle="%(ENC)s"' % \
|
||||||
|
NS.__dict__
|
||||||
|
_env_bot = '</%(ENV_T)s:Envelope>\n' % NS.__dict__
|
||||||
|
|
||||||
|
# Namespaces potentially defined in the Envelope tag.
|
||||||
|
|
||||||
|
_env_ns = {NS.ENC: NS.ENC_T, NS.ENV: NS.ENV_T,
|
||||||
|
NS.XSD: NS.XSD_T, NS.XSD2: NS.XSD2_T, NS.XSD3: NS.XSD3_T,
|
||||||
|
NS.XSI: NS.XSI_T, NS.XSI2: NS.XSI2_T, NS.XSI3: NS.XSI3_T}
|
||||||
|
|
||||||
|
def __init__(self, args = (), kw = {}, method = None, namespace = None,
|
||||||
|
header = None, methodattrs = None, envelope = 1, encoding = 'UTF-8',
|
||||||
|
use_refs = 0, config = Config, noroot = 0):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
self.args = args
|
||||||
|
self.kw = kw
|
||||||
|
self.envelope = envelope
|
||||||
|
self.encoding = encoding
|
||||||
|
self.method = method
|
||||||
|
self.namespace = namespace
|
||||||
|
self.header = header
|
||||||
|
self.methodattrs= methodattrs
|
||||||
|
self.use_refs = use_refs
|
||||||
|
self.config = config
|
||||||
|
self.out = []
|
||||||
|
self.tcounter = 0
|
||||||
|
self.ncounter = 1
|
||||||
|
self.icounter = 1
|
||||||
|
self.envns = {}
|
||||||
|
self.ids = {}
|
||||||
|
self.depth = 0
|
||||||
|
self.multirefs = []
|
||||||
|
self.multis = 0
|
||||||
|
self.body = not isinstance(args, bodyType)
|
||||||
|
self.noroot = noroot
|
||||||
|
|
||||||
|
def build(self):
|
||||||
|
if Config.debug: print "In build."
|
||||||
|
ns_map = {}
|
||||||
|
|
||||||
|
# Cache whether typing is on or not
|
||||||
|
typed = self.config.typed
|
||||||
|
|
||||||
|
if self.header:
|
||||||
|
# Create a header.
|
||||||
|
self.dump(self.header, "Header", typed = typed)
|
||||||
|
self.header = None # Wipe it out so no one is using it.
|
||||||
|
|
||||||
|
if self.body:
|
||||||
|
# Call genns to record that we've used SOAP-ENV.
|
||||||
|
self.depth += 1
|
||||||
|
body_ns = self.genns(ns_map, NS.ENV)[0]
|
||||||
|
self.out.append("<%sBody>\n" % body_ns)
|
||||||
|
|
||||||
|
if self.method:
|
||||||
|
self.depth += 1
|
||||||
|
a = ''
|
||||||
|
if self.methodattrs:
|
||||||
|
for (k, v) in self.methodattrs.items():
|
||||||
|
a += ' %s="%s"' % (k, v)
|
||||||
|
|
||||||
|
if self.namespace: # Use the namespace info handed to us
|
||||||
|
methodns, n = self.genns(ns_map, self.namespace)
|
||||||
|
else:
|
||||||
|
methodns, n = '', ''
|
||||||
|
|
||||||
|
self.out.append('<%s%s%s%s%s>\n' % (
|
||||||
|
methodns, self.method, n, a, self.genroot(ns_map)))
|
||||||
|
|
||||||
|
try:
|
||||||
|
if type(self.args) != TupleType:
|
||||||
|
args = (self.args,)
|
||||||
|
else:
|
||||||
|
args = self.args
|
||||||
|
|
||||||
|
for i in args:
|
||||||
|
self.dump(i, typed = typed, ns_map = ns_map)
|
||||||
|
|
||||||
|
if hasattr(self.config, "argsOrdering") and self.config.argsOrdering.has_key(self.method):
|
||||||
|
for k in self.config.argsOrdering.get(self.method):
|
||||||
|
self.dump(self.kw.get(k), k, typed = typed, ns_map = ns_map)
|
||||||
|
else:
|
||||||
|
for (k, v) in self.kw.items():
|
||||||
|
self.dump(v, k, typed = typed, ns_map = ns_map)
|
||||||
|
|
||||||
|
except RecursionError:
|
||||||
|
if self.use_refs == 0:
|
||||||
|
# restart
|
||||||
|
b = SOAPBuilder(args = self.args, kw = self.kw,
|
||||||
|
method = self.method, namespace = self.namespace,
|
||||||
|
header = self.header, methodattrs = self.methodattrs,
|
||||||
|
envelope = self.envelope, encoding = self.encoding,
|
||||||
|
use_refs = 1, config = self.config)
|
||||||
|
return b.build()
|
||||||
|
raise
|
||||||
|
|
||||||
|
if self.method:
|
||||||
|
self.out.append("</%s%s>\n" % (methodns, self.method))
|
||||||
|
self.depth -= 1
|
||||||
|
|
||||||
|
if self.body:
|
||||||
|
# dump may add to self.multirefs, but the for loop will keep
|
||||||
|
# going until it has used all of self.multirefs, even those
|
||||||
|
# entries added while in the loop.
|
||||||
|
|
||||||
|
self.multis = 1
|
||||||
|
|
||||||
|
for obj, tag in self.multirefs:
|
||||||
|
self.dump(obj, tag, typed = typed, ns_map = ns_map)
|
||||||
|
|
||||||
|
self.out.append("</%sBody>\n" % body_ns)
|
||||||
|
self.depth -= 1
|
||||||
|
|
||||||
|
if self.envelope:
|
||||||
|
e = map (lambda ns: ' xmlns:%s="%s"' % (ns[1], ns[0]),
|
||||||
|
self.envns.items())
|
||||||
|
|
||||||
|
self.out = ['<', self._env_top] + e + ['>\n'] + \
|
||||||
|
self.out + \
|
||||||
|
[self._env_bot]
|
||||||
|
|
||||||
|
if self.encoding != None:
|
||||||
|
self.out.insert(0, self._xml_enc_top % self.encoding)
|
||||||
|
return ''.join(self.out).encode(self.encoding)
|
||||||
|
|
||||||
|
self.out.insert(0, self._xml_top)
|
||||||
|
return ''.join(self.out)
|
||||||
|
|
||||||
|
def gentag(self):
|
||||||
|
if Config.debug: print "In gentag."
|
||||||
|
self.tcounter += 1
|
||||||
|
return "v%d" % self.tcounter
|
||||||
|
|
||||||
|
def genns(self, ns_map, nsURI):
|
||||||
|
if nsURI == None:
|
||||||
|
return ('', '')
|
||||||
|
|
||||||
|
if type(nsURI) == TupleType: # already a tuple
|
||||||
|
if len(nsURI) == 2:
|
||||||
|
ns, nsURI = nsURI
|
||||||
|
else:
|
||||||
|
ns, nsURI = None, nsURI[0]
|
||||||
|
else:
|
||||||
|
ns = None
|
||||||
|
|
||||||
|
if ns_map.has_key(nsURI):
|
||||||
|
return (ns_map[nsURI] + ':', '')
|
||||||
|
|
||||||
|
if self._env_ns.has_key(nsURI):
|
||||||
|
ns = self.envns[nsURI] = ns_map[nsURI] = self._env_ns[nsURI]
|
||||||
|
return (ns + ':', '')
|
||||||
|
|
||||||
|
if not ns:
|
||||||
|
ns = "ns%d" % self.ncounter
|
||||||
|
self.ncounter += 1
|
||||||
|
ns_map[nsURI] = ns
|
||||||
|
if self.config.buildWithNamespacePrefix:
|
||||||
|
return (ns + ':', ' xmlns:%s="%s"' % (ns, nsURI))
|
||||||
|
else:
|
||||||
|
return ('', ' xmlns="%s"' % (nsURI))
|
||||||
|
|
||||||
|
def genroot(self, ns_map):
|
||||||
|
if self.noroot:
|
||||||
|
return ''
|
||||||
|
|
||||||
|
if self.depth != 2:
|
||||||
|
return ''
|
||||||
|
|
||||||
|
ns, n = self.genns(ns_map, NS.ENC)
|
||||||
|
return ' %sroot="%d"%s' % (ns, not self.multis, n)
|
||||||
|
|
||||||
|
# checkref checks an element to see if it needs to be encoded as a
|
||||||
|
# multi-reference element or not. If it returns None, the element has
|
||||||
|
# been handled and the caller can continue with subsequent elements.
|
||||||
|
# If it returns a string, the string should be included in the opening
|
||||||
|
# tag of the marshaled element.
|
||||||
|
|
||||||
|
def checkref(self, obj, tag, ns_map):
|
||||||
|
if self.depth < 2:
|
||||||
|
return ''
|
||||||
|
|
||||||
|
if not self.ids.has_key(id(obj)):
|
||||||
|
n = self.ids[id(obj)] = self.icounter
|
||||||
|
self.icounter = n + 1
|
||||||
|
|
||||||
|
if self.use_refs == 0:
|
||||||
|
return ''
|
||||||
|
|
||||||
|
if self.depth == 2:
|
||||||
|
return ' id="i%d"' % n
|
||||||
|
|
||||||
|
self.multirefs.append((obj, tag))
|
||||||
|
else:
|
||||||
|
if self.use_refs == 0:
|
||||||
|
raise RecursionError, "Cannot serialize recursive object"
|
||||||
|
|
||||||
|
n = self.ids[id(obj)]
|
||||||
|
|
||||||
|
if self.multis and self.depth == 2:
|
||||||
|
return ' id="i%d"' % n
|
||||||
|
|
||||||
|
self.out.append('<%s href="#i%d"%s/>\n' %
|
||||||
|
(tag, n, self.genroot(ns_map)))
|
||||||
|
return None
|
||||||
|
|
||||||
|
# dumpers
|
||||||
|
|
||||||
|
def dump(self, obj, tag = None, typed = 1, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump.", "obj=", obj
|
||||||
|
ns_map = ns_map.copy()
|
||||||
|
self.depth += 1
|
||||||
|
|
||||||
|
if type(tag) not in (NoneType, StringType, UnicodeType):
|
||||||
|
raise KeyError, "tag must be a string or None"
|
||||||
|
|
||||||
|
try:
|
||||||
|
meth = getattr(self, "dump_" + type(obj).__name__)
|
||||||
|
except AttributeError:
|
||||||
|
if type(obj) == LongType:
|
||||||
|
obj_type = "integer"
|
||||||
|
elif pythonHasBooleanType and type(obj) == BooleanType:
|
||||||
|
obj_type = "boolean"
|
||||||
|
else:
|
||||||
|
obj_type = type(obj).__name__
|
||||||
|
|
||||||
|
self.out.append(self.dumper(None, obj_type, obj, tag, typed,
|
||||||
|
ns_map, self.genroot(ns_map)))
|
||||||
|
else:
|
||||||
|
meth(obj, tag, typed, ns_map)
|
||||||
|
|
||||||
|
|
||||||
|
self.depth -= 1
|
||||||
|
|
||||||
|
# generic dumper
|
||||||
|
def dumper(self, nsURI, obj_type, obj, tag, typed = 1, ns_map = {},
|
||||||
|
rootattr = '', id = '',
|
||||||
|
xml = '<%(tag)s%(type)s%(id)s%(attrs)s%(root)s>%(data)s</%(tag)s>\n'):
|
||||||
|
if Config.debug: print "In dumper."
|
||||||
|
|
||||||
|
if nsURI == None:
|
||||||
|
nsURI = self.config.typesNamespaceURI
|
||||||
|
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
a = n = t = ''
|
||||||
|
if typed and obj_type:
|
||||||
|
ns, n = self.genns(ns_map, nsURI)
|
||||||
|
ins = self.genns(ns_map, self.config.schemaNamespaceURI)[0]
|
||||||
|
t = ' %stype="%s%s"%s' % (ins, ns, obj_type, n)
|
||||||
|
|
||||||
|
try: a = obj._marshalAttrs(ns_map, self)
|
||||||
|
except: pass
|
||||||
|
|
||||||
|
try: data = obj._marshalData()
|
||||||
|
except:
|
||||||
|
if (obj_type != "string"): # strings are already encoded
|
||||||
|
data = cgi.escape(str(obj))
|
||||||
|
else:
|
||||||
|
data = obj
|
||||||
|
|
||||||
|
|
||||||
|
return xml % {"tag": tag, "type": t, "data": data, "root": rootattr,
|
||||||
|
"id": id, "attrs": a}
|
||||||
|
|
||||||
|
def dump_float(self, obj, tag, typed = 1, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_float."
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
if Config.strict_range:
|
||||||
|
doubleType(obj)
|
||||||
|
|
||||||
|
if fpconst.isPosInf(obj):
|
||||||
|
obj = "INF"
|
||||||
|
elif fpconst.isNegInf(obj):
|
||||||
|
obj = "-INF"
|
||||||
|
elif fpconst.isNaN(obj):
|
||||||
|
obj = "NaN"
|
||||||
|
else:
|
||||||
|
obj = str(obj)
|
||||||
|
|
||||||
|
# Note: python 'float' is actually a SOAP 'double'.
|
||||||
|
self.out.append(self.dumper(None, "double", obj, tag, typed, ns_map,
|
||||||
|
self.genroot(ns_map)))
|
||||||
|
|
||||||
|
def dump_string(self, obj, tag, typed = 0, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_string."
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
id = self.checkref(obj, tag, ns_map)
|
||||||
|
if id == None:
|
||||||
|
return
|
||||||
|
|
||||||
|
try: data = obj._marshalData()
|
||||||
|
except: data = obj
|
||||||
|
|
||||||
|
self.out.append(self.dumper(None, "string", cgi.escape(data), tag,
|
||||||
|
typed, ns_map, self.genroot(ns_map), id))
|
||||||
|
|
||||||
|
dump_str = dump_string # For Python 2.2+
|
||||||
|
dump_unicode = dump_string
|
||||||
|
|
||||||
|
def dump_None(self, obj, tag, typed = 0, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_None."
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
ns = self.genns(ns_map, self.config.schemaNamespaceURI)[0]
|
||||||
|
|
||||||
|
self.out.append('<%s %snull="1"%s/>\n' %
|
||||||
|
(tag, ns, self.genroot(ns_map)))
|
||||||
|
|
||||||
|
dump_NoneType = dump_None # For Python 2.2+
|
||||||
|
|
||||||
|
def dump_list(self, obj, tag, typed = 1, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_list.", "obj=", obj
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
if type(obj) == InstanceType:
|
||||||
|
data = obj.data
|
||||||
|
else:
|
||||||
|
data = obj
|
||||||
|
|
||||||
|
id = self.checkref(obj, tag, ns_map)
|
||||||
|
if id == None:
|
||||||
|
return
|
||||||
|
|
||||||
|
try:
|
||||||
|
sample = data[0]
|
||||||
|
empty = 0
|
||||||
|
except:
|
||||||
|
# preserve type if present
|
||||||
|
if getattr(obj,"_typed",None) and getattr(obj,"_type",None):
|
||||||
|
if getattr(obj, "_complexType", None):
|
||||||
|
sample = typedArrayType(typed=obj._type,
|
||||||
|
complexType = obj._complexType)
|
||||||
|
sample._typename = obj._type
|
||||||
|
obj._ns = NS.URN
|
||||||
|
else:
|
||||||
|
sample = typedArrayType(typed=obj._type)
|
||||||
|
else:
|
||||||
|
sample = structType()
|
||||||
|
empty = 1
|
||||||
|
|
||||||
|
# First scan list to see if all are the same type
|
||||||
|
same_type = 1
|
||||||
|
|
||||||
|
if not empty:
|
||||||
|
for i in data[1:]:
|
||||||
|
if type(sample) != type(i) or \
|
||||||
|
(type(sample) == InstanceType and \
|
||||||
|
sample.__class__ != i.__class__):
|
||||||
|
same_type = 0
|
||||||
|
break
|
||||||
|
|
||||||
|
ndecl = ''
|
||||||
|
if same_type:
|
||||||
|
if (isinstance(sample, structType)) or \
|
||||||
|
type(sample) == DictType or \
|
||||||
|
(isinstance(sample, anyType) and \
|
||||||
|
(getattr(sample, "_complexType", None) and \
|
||||||
|
sample._complexType)): # force to urn struct
|
||||||
|
try:
|
||||||
|
tns = obj._ns or NS.URN
|
||||||
|
except:
|
||||||
|
tns = NS.URN
|
||||||
|
|
||||||
|
ns, ndecl = self.genns(ns_map, tns)
|
||||||
|
|
||||||
|
try:
|
||||||
|
typename = sample._typename
|
||||||
|
except:
|
||||||
|
typename = "SOAPStruct"
|
||||||
|
|
||||||
|
t = ns + typename
|
||||||
|
|
||||||
|
elif isinstance(sample, anyType):
|
||||||
|
ns = sample._validNamespaceURI(self.config.typesNamespaceURI,
|
||||||
|
self.config.strictNamespaces)
|
||||||
|
if ns:
|
||||||
|
ns, ndecl = self.genns(ns_map, ns)
|
||||||
|
t = ns + sample._type
|
||||||
|
else:
|
||||||
|
t = 'ur-type'
|
||||||
|
else:
|
||||||
|
typename = type(sample).__name__
|
||||||
|
|
||||||
|
# For Python 2.2+
|
||||||
|
if type(sample) == StringType: typename = 'string'
|
||||||
|
|
||||||
|
# HACK: python 'float' is actually a SOAP 'double'.
|
||||||
|
if typename=="float": typename="double"
|
||||||
|
t = self.genns(ns_map, self.config.typesNamespaceURI)[0] + \
|
||||||
|
typename
|
||||||
|
|
||||||
|
else:
|
||||||
|
t = self.genns(ns_map, self.config.typesNamespaceURI)[0] + \
|
||||||
|
"ur-type"
|
||||||
|
|
||||||
|
try: a = obj._marshalAttrs(ns_map, self)
|
||||||
|
except: a = ''
|
||||||
|
|
||||||
|
ens, edecl = self.genns(ns_map, NS.ENC)
|
||||||
|
ins, idecl = self.genns(ns_map, self.config.schemaNamespaceURI)
|
||||||
|
|
||||||
|
self.out.append(
|
||||||
|
'<%s %sarrayType="%s[%d]" %stype="%sArray"%s%s%s%s%s%s>\n' %
|
||||||
|
(tag, ens, t, len(data), ins, ens, ndecl, edecl, idecl,
|
||||||
|
self.genroot(ns_map), id, a))
|
||||||
|
|
||||||
|
typed = not same_type
|
||||||
|
|
||||||
|
try: elemsname = obj._elemsname
|
||||||
|
except: elemsname = "item"
|
||||||
|
|
||||||
|
for i in data:
|
||||||
|
self.dump(i, elemsname, typed, ns_map)
|
||||||
|
|
||||||
|
self.out.append('</%s>\n' % tag)
|
||||||
|
|
||||||
|
dump_tuple = dump_list
|
||||||
|
|
||||||
|
def dump_dictionary(self, obj, tag, typed = 1, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_dictionary."
|
||||||
|
tag = tag or self.gentag()
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
id = self.checkref(obj, tag, ns_map)
|
||||||
|
if id == None:
|
||||||
|
return
|
||||||
|
|
||||||
|
try: a = obj._marshalAttrs(ns_map, self)
|
||||||
|
except: a = ''
|
||||||
|
|
||||||
|
self.out.append('<%s%s%s%s>\n' %
|
||||||
|
(tag, id, a, self.genroot(ns_map)))
|
||||||
|
|
||||||
|
for (k, v) in obj.items():
|
||||||
|
if k[0] != "_":
|
||||||
|
self.dump(v, k, 1, ns_map)
|
||||||
|
|
||||||
|
self.out.append('</%s>\n' % tag)
|
||||||
|
|
||||||
|
dump_dict = dump_dictionary # For Python 2.2+
|
||||||
|
|
||||||
|
def dump_instance(self, obj, tag, typed = 1, ns_map = {}):
|
||||||
|
if Config.debug: print "In dump_instance.", "obj=", obj, "tag=", tag
|
||||||
|
if not tag:
|
||||||
|
# If it has a name use it.
|
||||||
|
if isinstance(obj, anyType) and obj._name:
|
||||||
|
tag = obj._name
|
||||||
|
else:
|
||||||
|
tag = self.gentag()
|
||||||
|
tag = toXMLname(tag) # convert from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
if isinstance(obj, arrayType): # Array
|
||||||
|
self.dump_list(obj, tag, typed, ns_map)
|
||||||
|
return
|
||||||
|
|
||||||
|
if isinstance(obj, faultType): # Fault
|
||||||
|
cns, cdecl = self.genns(ns_map, NS.ENC)
|
||||||
|
vns, vdecl = self.genns(ns_map, NS.ENV)
|
||||||
|
self.out.append('''<%sFault %sroot="1"%s%s>
|
||||||
|
<faultcode>%s</faultcode>
|
||||||
|
<faultstring>%s</faultstring>
|
||||||
|
''' % (vns, cns, vdecl, cdecl, obj.faultcode, obj.faultstring))
|
||||||
|
if hasattr(obj, "detail"):
|
||||||
|
self.dump(obj.detail, "detail", typed, ns_map)
|
||||||
|
self.out.append("</%sFault>\n" % vns)
|
||||||
|
return
|
||||||
|
|
||||||
|
r = self.genroot(ns_map)
|
||||||
|
|
||||||
|
try: a = obj._marshalAttrs(ns_map, self)
|
||||||
|
except: a = ''
|
||||||
|
|
||||||
|
if isinstance(obj, voidType): # void
|
||||||
|
self.out.append("<%s%s%s></%s>\n" % (tag, a, r, tag))
|
||||||
|
return
|
||||||
|
|
||||||
|
id = self.checkref(obj, tag, ns_map)
|
||||||
|
if id == None:
|
||||||
|
return
|
||||||
|
|
||||||
|
if isinstance(obj, structType):
|
||||||
|
# Check for namespace
|
||||||
|
ndecl = ''
|
||||||
|
ns = obj._validNamespaceURI(self.config.typesNamespaceURI,
|
||||||
|
self.config.strictNamespaces)
|
||||||
|
if ns:
|
||||||
|
ns, ndecl = self.genns(ns_map, ns)
|
||||||
|
tag = ns + tag
|
||||||
|
self.out.append("<%s%s%s%s%s>\n" % (tag, ndecl, id, a, r))
|
||||||
|
|
||||||
|
keylist = obj.__dict__.keys()
|
||||||
|
|
||||||
|
# first write out items with order information
|
||||||
|
if hasattr(obj, '_keyord'):
|
||||||
|
for i in range(len(obj._keyord)):
|
||||||
|
self.dump(obj._aslist(i), obj._keyord[i], 1, ns_map)
|
||||||
|
keylist.remove(obj._keyord[i])
|
||||||
|
|
||||||
|
# now write out the rest
|
||||||
|
for k in keylist:
|
||||||
|
if (k[0] != "_"):
|
||||||
|
self.dump(getattr(obj,k), k, 1, ns_map)
|
||||||
|
|
||||||
|
if isinstance(obj, bodyType):
|
||||||
|
self.multis = 1
|
||||||
|
|
||||||
|
for v, k in self.multirefs:
|
||||||
|
self.dump(v, k, typed = typed, ns_map = ns_map)
|
||||||
|
|
||||||
|
self.out.append('</%s>\n' % tag)
|
||||||
|
|
||||||
|
elif isinstance(obj, anyType):
|
||||||
|
t = ''
|
||||||
|
|
||||||
|
if typed:
|
||||||
|
ns = obj._validNamespaceURI(self.config.typesNamespaceURI,
|
||||||
|
self.config.strictNamespaces)
|
||||||
|
if ns:
|
||||||
|
ons, ondecl = self.genns(ns_map, ns)
|
||||||
|
ins, indecl = self.genns(ns_map,
|
||||||
|
self.config.schemaNamespaceURI)
|
||||||
|
t = ' %stype="%s%s"%s%s' % \
|
||||||
|
(ins, ons, obj._type, ondecl, indecl)
|
||||||
|
|
||||||
|
self.out.append('<%s%s%s%s%s>%s</%s>\n' %
|
||||||
|
(tag, t, id, a, r, obj._marshalData(), tag))
|
||||||
|
|
||||||
|
else: # Some Class
|
||||||
|
self.out.append('<%s%s%s>\n' % (tag, id, r))
|
||||||
|
|
||||||
|
for (k, v) in obj.__dict__.items():
|
||||||
|
if k[0] != "_":
|
||||||
|
self.dump(v, k, 1, ns_map)
|
||||||
|
|
||||||
|
self.out.append('</%s>\n' % tag)
|
||||||
|
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# SOAPBuilder's more public interface
|
||||||
|
################################################################################
|
||||||
|
def buildSOAP(args=(), kw={}, method=None, namespace=None, header=None,
|
||||||
|
methodattrs=None,envelope=1,encoding='UTF-8',config=Config,noroot = 0):
|
||||||
|
t = SOAPBuilder(args=args,kw=kw, method=method, namespace=namespace,
|
||||||
|
header=header, methodattrs=methodattrs,envelope=envelope,
|
||||||
|
encoding=encoding, config=config,noroot=noroot)
|
||||||
|
return t.build()
|
||||||
706
others/SOAPpy/Server.py
Normal file
706
others/SOAPpy/Server.py
Normal file
@ -0,0 +1,706 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
#
|
||||||
|
# SOAPpy - Cayce Ullman (cayce@actzero.com)
|
||||||
|
# Brian Matthews (blm@actzero.com)
|
||||||
|
# Gregory Warnes (gregory_r_warnes@groton.pfizer.com)
|
||||||
|
# Christopher Blunck (blunck@gst.com)
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from __future__ import nested_scopes
|
||||||
|
|
||||||
|
#import xml.sax
|
||||||
|
import re
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
import SocketServer
|
||||||
|
from types import *
|
||||||
|
import BaseHTTPServer
|
||||||
|
import thread
|
||||||
|
|
||||||
|
# SOAPpy modules
|
||||||
|
from Parser import parseSOAPRPC
|
||||||
|
from Config import Config
|
||||||
|
from Types import faultType, voidType, simplify
|
||||||
|
from NS import NS
|
||||||
|
from SOAPBuilder import buildSOAP
|
||||||
|
from Utilities import debugHeader, debugFooter
|
||||||
|
|
||||||
|
try: from M2Crypto import SSL
|
||||||
|
except: pass
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Call context dictionary
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
_contexts = dict()
|
||||||
|
|
||||||
|
def GetSOAPContext():
|
||||||
|
global _contexts
|
||||||
|
return _contexts[thread.get_ident()]
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Server
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
# Method Signature class for adding extra info to registered funcs, right now
|
||||||
|
# used just to indicate it should be called with keywords, instead of ordered
|
||||||
|
# params.
|
||||||
|
class MethodSig:
|
||||||
|
def __init__(self, func, keywords=0, context=0):
|
||||||
|
self.func = func
|
||||||
|
self.keywords = keywords
|
||||||
|
self.context = context
|
||||||
|
self.__name__ = func.__name__
|
||||||
|
|
||||||
|
def __call__(self, *args, **kw):
|
||||||
|
return apply(self.func,args,kw)
|
||||||
|
|
||||||
|
class SOAPContext:
|
||||||
|
def __init__(self, header, body, attrs, xmldata, connection, httpheaders,
|
||||||
|
soapaction):
|
||||||
|
|
||||||
|
self.header = header
|
||||||
|
self.body = body
|
||||||
|
self.attrs = attrs
|
||||||
|
self.xmldata = xmldata
|
||||||
|
self.connection = connection
|
||||||
|
self.httpheaders= httpheaders
|
||||||
|
self.soapaction = soapaction
|
||||||
|
|
||||||
|
# A class to describe how header messages are handled
|
||||||
|
class HeaderHandler:
|
||||||
|
# Initially fail out if there are any problems.
|
||||||
|
def __init__(self, header, attrs):
|
||||||
|
for i in header.__dict__.keys():
|
||||||
|
if i[0] == "_":
|
||||||
|
continue
|
||||||
|
|
||||||
|
d = getattr(header, i)
|
||||||
|
|
||||||
|
try:
|
||||||
|
fault = int(attrs[id(d)][(NS.ENV, 'mustUnderstand')])
|
||||||
|
except:
|
||||||
|
fault = 0
|
||||||
|
|
||||||
|
if fault:
|
||||||
|
raise faultType, ("%s:MustUnderstand" % NS.ENV_T,
|
||||||
|
"Required Header Misunderstood",
|
||||||
|
"%s" % i)
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# SOAP Server
|
||||||
|
################################################################################
|
||||||
|
class SOAPServerBase:
|
||||||
|
|
||||||
|
def get_request(self):
|
||||||
|
sock, addr = SocketServer.TCPServer.get_request(self)
|
||||||
|
|
||||||
|
if self.ssl_context:
|
||||||
|
sock = SSL.Connection(self.ssl_context, sock)
|
||||||
|
sock._setup_ssl(addr)
|
||||||
|
if sock.accept_ssl() != 1:
|
||||||
|
raise socket.error, "Couldn't accept SSL connection"
|
||||||
|
|
||||||
|
return sock, addr
|
||||||
|
|
||||||
|
def registerObject(self, object, namespace = '', path = ''):
|
||||||
|
if namespace == '' and path == '': namespace = self.namespace
|
||||||
|
if namespace == '' and path != '':
|
||||||
|
namespace = path.replace("/", ":")
|
||||||
|
if namespace[0] == ":": namespace = namespace[1:]
|
||||||
|
self.objmap[namespace] = object
|
||||||
|
|
||||||
|
def registerFunction(self, function, namespace = '', funcName = None,
|
||||||
|
path = ''):
|
||||||
|
if not funcName : funcName = function.__name__
|
||||||
|
if namespace == '' and path == '': namespace = self.namespace
|
||||||
|
if namespace == '' and path != '':
|
||||||
|
namespace = path.replace("/", ":")
|
||||||
|
if namespace[0] == ":": namespace = namespace[1:]
|
||||||
|
if self.funcmap.has_key(namespace):
|
||||||
|
self.funcmap[namespace][funcName] = function
|
||||||
|
else:
|
||||||
|
self.funcmap[namespace] = {funcName : function}
|
||||||
|
|
||||||
|
def registerKWObject(self, object, namespace = '', path = ''):
|
||||||
|
if namespace == '' and path == '': namespace = self.namespace
|
||||||
|
if namespace == '' and path != '':
|
||||||
|
namespace = path.replace("/", ":")
|
||||||
|
if namespace[0] == ":": namespace = namespace[1:]
|
||||||
|
for i in dir(object.__class__):
|
||||||
|
if i[0] != "_" and callable(getattr(object, i)):
|
||||||
|
self.registerKWFunction(getattr(object,i), namespace)
|
||||||
|
|
||||||
|
# convenience - wraps your func for you.
|
||||||
|
def registerKWFunction(self, function, namespace = '', funcName = None,
|
||||||
|
path = ''):
|
||||||
|
if namespace == '' and path == '': namespace = self.namespace
|
||||||
|
if namespace == '' and path != '':
|
||||||
|
namespace = path.replace("/", ":")
|
||||||
|
if namespace[0] == ":": namespace = namespace[1:]
|
||||||
|
self.registerFunction(MethodSig(function,keywords=1), namespace,
|
||||||
|
funcName)
|
||||||
|
|
||||||
|
def unregisterObject(self, object, namespace = '', path = ''):
|
||||||
|
if namespace == '' and path == '': namespace = self.namespace
|
||||||
|
if namespace == '' and path != '':
|
||||||
|
namespace = path.replace("/", ":")
|
||||||
|
if namespace[0] == ":": namespace = namespace[1:]
|
||||||
|
|
||||||
|
del self.objmap[namespace]
|
||||||
|
|
||||||
|
class SOAPRequestHandler(BaseHTTPServer.BaseHTTPRequestHandler):
|
||||||
|
def version_string(self):
|
||||||
|
return '<a href="http://pywebsvcs.sf.net">' + \
|
||||||
|
'SOAPpy ' + __version__ + '</a> (Python ' + \
|
||||||
|
sys.version.split()[0] + ')'
|
||||||
|
|
||||||
|
def date_time_string(self):
|
||||||
|
self.__last_date_time_string = \
|
||||||
|
BaseHTTPServer.BaseHTTPRequestHandler.\
|
||||||
|
date_time_string(self)
|
||||||
|
|
||||||
|
return self.__last_date_time_string
|
||||||
|
|
||||||
|
def do_POST(self):
|
||||||
|
global _contexts
|
||||||
|
|
||||||
|
status = 500
|
||||||
|
try:
|
||||||
|
if self.server.config.dumpHeadersIn:
|
||||||
|
s = 'Incoming HTTP headers'
|
||||||
|
debugHeader(s)
|
||||||
|
print self.raw_requestline.strip()
|
||||||
|
print "\n".join(map (lambda x: x.strip(),
|
||||||
|
self.headers.headers))
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
data = self.rfile.read(int(self.headers["Content-length"]))
|
||||||
|
|
||||||
|
if self.server.config.dumpSOAPIn:
|
||||||
|
s = 'Incoming SOAP'
|
||||||
|
debugHeader(s)
|
||||||
|
print data,
|
||||||
|
if data[-1] != '\n':
|
||||||
|
print
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
(r, header, body, attrs) = \
|
||||||
|
parseSOAPRPC(data, header = 1, body = 1, attrs = 1)
|
||||||
|
|
||||||
|
method = r._name
|
||||||
|
args = r._aslist()
|
||||||
|
kw = r._asdict()
|
||||||
|
|
||||||
|
if Config.simplify_objects:
|
||||||
|
args = simplify(args)
|
||||||
|
kw = simplify(kw)
|
||||||
|
|
||||||
|
# Handle mixed named and unnamed arguments by assuming
|
||||||
|
# that all arguments with names of the form "v[0-9]+"
|
||||||
|
# are unnamed and should be passed in numeric order,
|
||||||
|
# other arguments are named and should be passed using
|
||||||
|
# this name.
|
||||||
|
|
||||||
|
# This is a non-standard exension to the SOAP protocol,
|
||||||
|
# but is supported by Apache AXIS.
|
||||||
|
|
||||||
|
# It is enabled by default. To disable, set
|
||||||
|
# Config.specialArgs to False.
|
||||||
|
|
||||||
|
if Config.specialArgs:
|
||||||
|
|
||||||
|
ordered_args = {}
|
||||||
|
named_args = {}
|
||||||
|
|
||||||
|
for (k,v) in kw.items():
|
||||||
|
|
||||||
|
if k[0]=="v":
|
||||||
|
try:
|
||||||
|
i = int(k[1:])
|
||||||
|
ordered_args[i] = v
|
||||||
|
except ValueError:
|
||||||
|
named_args[str(k)] = v
|
||||||
|
|
||||||
|
else:
|
||||||
|
named_args[str(k)] = v
|
||||||
|
|
||||||
|
# We have to decide namespace precedence
|
||||||
|
# I'm happy with the following scenario
|
||||||
|
# if r._ns is specified use it, if not check for
|
||||||
|
# a path, if it's specified convert it and use it as the
|
||||||
|
# namespace. If both are specified, use r._ns.
|
||||||
|
|
||||||
|
ns = r._ns
|
||||||
|
|
||||||
|
if len(self.path) > 1 and not ns:
|
||||||
|
ns = self.path.replace("/", ":")
|
||||||
|
if ns[0] == ":": ns = ns[1:]
|
||||||
|
|
||||||
|
# authorization method
|
||||||
|
a = None
|
||||||
|
|
||||||
|
keylist = ordered_args.keys()
|
||||||
|
keylist.sort()
|
||||||
|
|
||||||
|
# create list in proper order w/o names
|
||||||
|
tmp = map( lambda x: ordered_args[x], keylist)
|
||||||
|
ordered_args = tmp
|
||||||
|
|
||||||
|
#print '<-> Argument Matching Yielded:'
|
||||||
|
#print '<-> Ordered Arguments:' + str(ordered_args)
|
||||||
|
#print '<-> Named Arguments :' + str(named_args)
|
||||||
|
|
||||||
|
resp = ""
|
||||||
|
|
||||||
|
# For fault messages
|
||||||
|
if ns:
|
||||||
|
nsmethod = "%s:%s" % (ns, method)
|
||||||
|
else:
|
||||||
|
nsmethod = method
|
||||||
|
|
||||||
|
try:
|
||||||
|
# First look for registered functions
|
||||||
|
if self.server.funcmap.has_key(ns) and \
|
||||||
|
self.server.funcmap[ns].has_key(method):
|
||||||
|
f = self.server.funcmap[ns][method]
|
||||||
|
|
||||||
|
# look for the authorization method
|
||||||
|
if self.server.config.authMethod != None:
|
||||||
|
authmethod = self.server.config.authMethod
|
||||||
|
if self.server.funcmap.has_key(ns) and \
|
||||||
|
self.server.funcmap[ns].has_key(authmethod):
|
||||||
|
a = self.server.funcmap[ns][authmethod]
|
||||||
|
else:
|
||||||
|
# Now look at registered objects
|
||||||
|
# Check for nested attributes. This works even if
|
||||||
|
# there are none, because the split will return
|
||||||
|
# [method]
|
||||||
|
f = self.server.objmap[ns]
|
||||||
|
|
||||||
|
# Look for the authorization method
|
||||||
|
if self.server.config.authMethod != None:
|
||||||
|
authmethod = self.server.config.authMethod
|
||||||
|
if hasattr(f, authmethod):
|
||||||
|
a = getattr(f, authmethod)
|
||||||
|
|
||||||
|
# then continue looking for the method
|
||||||
|
l = method.split(".")
|
||||||
|
for i in l:
|
||||||
|
f = getattr(f, i)
|
||||||
|
except:
|
||||||
|
info = sys.exc_info()
|
||||||
|
try:
|
||||||
|
resp = buildSOAP(faultType("%s:Client" % NS.ENV_T,
|
||||||
|
"Method Not Found",
|
||||||
|
"%s : %s %s %s" % (nsmethod,
|
||||||
|
info[0],
|
||||||
|
info[1],
|
||||||
|
info[2])),
|
||||||
|
encoding = self.server.encoding,
|
||||||
|
config = self.server.config)
|
||||||
|
finally:
|
||||||
|
del info
|
||||||
|
status = 500
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
if header:
|
||||||
|
x = HeaderHandler(header, attrs)
|
||||||
|
|
||||||
|
fr = 1
|
||||||
|
|
||||||
|
# call context book keeping
|
||||||
|
# We're stuffing the method into the soapaction if there
|
||||||
|
# isn't one, someday, we'll set that on the client
|
||||||
|
# and it won't be necessary here
|
||||||
|
# for now we're doing both
|
||||||
|
|
||||||
|
if "SOAPAction".lower() not in self.headers.keys() or \
|
||||||
|
self.headers["SOAPAction"] == "\"\"":
|
||||||
|
self.headers["SOAPAction"] = method
|
||||||
|
|
||||||
|
thread_id = thread.get_ident()
|
||||||
|
_contexts[thread_id] = SOAPContext(header, body,
|
||||||
|
attrs, data,
|
||||||
|
self.connection,
|
||||||
|
self.headers,
|
||||||
|
self.headers["SOAPAction"])
|
||||||
|
|
||||||
|
# Do an authorization check
|
||||||
|
if a != None:
|
||||||
|
if not apply(a, (), {"_SOAPContext" :
|
||||||
|
_contexts[thread_id] }):
|
||||||
|
raise faultType("%s:Server" % NS.ENV_T,
|
||||||
|
"Authorization failed.",
|
||||||
|
"%s" % nsmethod)
|
||||||
|
|
||||||
|
# If it's wrapped, some special action may be needed
|
||||||
|
if isinstance(f, MethodSig):
|
||||||
|
c = None
|
||||||
|
|
||||||
|
if f.context: # retrieve context object
|
||||||
|
c = _contexts[thread_id]
|
||||||
|
|
||||||
|
if Config.specialArgs:
|
||||||
|
if c:
|
||||||
|
named_args["_SOAPContext"] = c
|
||||||
|
fr = apply(f, ordered_args, named_args)
|
||||||
|
elif f.keywords:
|
||||||
|
# This is lame, but have to de-unicode
|
||||||
|
# keywords
|
||||||
|
|
||||||
|
strkw = {}
|
||||||
|
|
||||||
|
for (k, v) in kw.items():
|
||||||
|
strkw[str(k)] = v
|
||||||
|
if c:
|
||||||
|
strkw["_SOAPContext"] = c
|
||||||
|
fr = apply(f, (), strkw)
|
||||||
|
elif c:
|
||||||
|
fr = apply(f, args, {'_SOAPContext':c})
|
||||||
|
else:
|
||||||
|
fr = apply(f, args, {})
|
||||||
|
|
||||||
|
else:
|
||||||
|
if Config.specialArgs:
|
||||||
|
fr = apply(f, ordered_args, named_args)
|
||||||
|
else:
|
||||||
|
fr = apply(f, args, {})
|
||||||
|
|
||||||
|
|
||||||
|
if type(fr) == type(self) and \
|
||||||
|
isinstance(fr, voidType):
|
||||||
|
resp = buildSOAP(kw = {'%sResponse' % method: fr},
|
||||||
|
encoding = self.server.encoding,
|
||||||
|
config = self.server.config)
|
||||||
|
else:
|
||||||
|
resp = buildSOAP(kw =
|
||||||
|
{'%sResponse' % method: {'Result': fr}},
|
||||||
|
encoding = self.server.encoding,
|
||||||
|
config = self.server.config)
|
||||||
|
|
||||||
|
# Clean up _contexts
|
||||||
|
if _contexts.has_key(thread_id):
|
||||||
|
del _contexts[thread_id]
|
||||||
|
|
||||||
|
except Exception, e:
|
||||||
|
import traceback
|
||||||
|
info = sys.exc_info()
|
||||||
|
|
||||||
|
try:
|
||||||
|
if self.server.config.dumpFaultInfo:
|
||||||
|
s = 'Method %s exception' % nsmethod
|
||||||
|
debugHeader(s)
|
||||||
|
traceback.print_exception(info[0], info[1],
|
||||||
|
info[2])
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
if isinstance(e, faultType):
|
||||||
|
f = e
|
||||||
|
else:
|
||||||
|
f = faultType("%s:Server" % NS.ENV_T,
|
||||||
|
"Method Failed",
|
||||||
|
"%s" % nsmethod)
|
||||||
|
|
||||||
|
if self.server.config.returnFaultInfo:
|
||||||
|
f._setDetail("".join(traceback.format_exception(
|
||||||
|
info[0], info[1], info[2])))
|
||||||
|
elif not hasattr(f, 'detail'):
|
||||||
|
f._setDetail("%s %s" % (info[0], info[1]))
|
||||||
|
finally:
|
||||||
|
del info
|
||||||
|
|
||||||
|
resp = buildSOAP(f, encoding = self.server.encoding,
|
||||||
|
config = self.server.config)
|
||||||
|
status = 500
|
||||||
|
else:
|
||||||
|
status = 200
|
||||||
|
except faultType, e:
|
||||||
|
import traceback
|
||||||
|
info = sys.exc_info()
|
||||||
|
try:
|
||||||
|
if self.server.config.dumpFaultInfo:
|
||||||
|
s = 'Received fault exception'
|
||||||
|
debugHeader(s)
|
||||||
|
traceback.print_exception(info[0], info[1],
|
||||||
|
info[2])
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
if self.server.config.returnFaultInfo:
|
||||||
|
e._setDetail("".join(traceback.format_exception(
|
||||||
|
info[0], info[1], info[2])))
|
||||||
|
elif not hasattr(e, 'detail'):
|
||||||
|
e._setDetail("%s %s" % (info[0], info[1]))
|
||||||
|
finally:
|
||||||
|
del info
|
||||||
|
|
||||||
|
resp = buildSOAP(e, encoding = self.server.encoding,
|
||||||
|
config = self.server.config)
|
||||||
|
status = 500
|
||||||
|
except Exception, e:
|
||||||
|
# internal error, report as HTTP server error
|
||||||
|
|
||||||
|
if self.server.config.dumpFaultInfo:
|
||||||
|
s = 'Internal exception %s' % e
|
||||||
|
import traceback
|
||||||
|
debugHeader(s)
|
||||||
|
info = sys.exc_info()
|
||||||
|
try:
|
||||||
|
traceback.print_exception(info[0], info[1], info[2])
|
||||||
|
finally:
|
||||||
|
del info
|
||||||
|
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
self.send_response(500)
|
||||||
|
self.end_headers()
|
||||||
|
|
||||||
|
if self.server.config.dumpHeadersOut and \
|
||||||
|
self.request_version != 'HTTP/0.9':
|
||||||
|
s = 'Outgoing HTTP headers'
|
||||||
|
debugHeader(s)
|
||||||
|
if self.responses.has_key(status):
|
||||||
|
s = ' ' + self.responses[status][0]
|
||||||
|
else:
|
||||||
|
s = ''
|
||||||
|
print "%s %d%s" % (self.protocol_version, 500, s)
|
||||||
|
print "Server:", self.version_string()
|
||||||
|
print "Date:", self.__last_date_time_string
|
||||||
|
debugFooter(s)
|
||||||
|
else:
|
||||||
|
# got a valid SOAP response
|
||||||
|
self.send_response(status)
|
||||||
|
|
||||||
|
t = 'text/xml';
|
||||||
|
if self.server.encoding != None:
|
||||||
|
t += '; charset="%s"' % self.server.encoding
|
||||||
|
self.send_header("Content-type", t)
|
||||||
|
self.send_header("Content-length", str(len(resp)))
|
||||||
|
self.end_headers()
|
||||||
|
|
||||||
|
if self.server.config.dumpHeadersOut and \
|
||||||
|
self.request_version != 'HTTP/0.9':
|
||||||
|
s = 'Outgoing HTTP headers'
|
||||||
|
debugHeader(s)
|
||||||
|
if self.responses.has_key(status):
|
||||||
|
s = ' ' + self.responses[status][0]
|
||||||
|
else:
|
||||||
|
s = ''
|
||||||
|
print "%s %d%s" % (self.protocol_version, status, s)
|
||||||
|
print "Server:", self.version_string()
|
||||||
|
print "Date:", self.__last_date_time_string
|
||||||
|
print "Content-type:", t
|
||||||
|
print "Content-length:", len(resp)
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
if self.server.config.dumpSOAPOut:
|
||||||
|
s = 'Outgoing SOAP'
|
||||||
|
debugHeader(s)
|
||||||
|
print resp,
|
||||||
|
if resp[-1] != '\n':
|
||||||
|
print
|
||||||
|
debugFooter(s)
|
||||||
|
|
||||||
|
self.wfile.write(resp)
|
||||||
|
self.wfile.flush()
|
||||||
|
|
||||||
|
# We should be able to shut down both a regular and an SSL
|
||||||
|
# connection, but under Python 2.1, calling shutdown on an
|
||||||
|
# SSL connections drops the output, so this work-around.
|
||||||
|
# This should be investigated more someday.
|
||||||
|
|
||||||
|
if self.server.config.SSLserver and \
|
||||||
|
isinstance(self.connection, SSL.Connection):
|
||||||
|
self.connection.set_shutdown(SSL.SSL_SENT_SHUTDOWN |
|
||||||
|
SSL.SSL_RECEIVED_SHUTDOWN)
|
||||||
|
else:
|
||||||
|
self.connection.shutdown(1)
|
||||||
|
|
||||||
|
def do_GET(self):
|
||||||
|
|
||||||
|
#print 'command ', self.command
|
||||||
|
#print 'path ', self.path
|
||||||
|
#print 'request_version', self.request_version
|
||||||
|
#print 'headers'
|
||||||
|
#print ' type ', self.headers.type
|
||||||
|
#print ' maintype', self.headers.maintype
|
||||||
|
#print ' subtype ', self.headers.subtype
|
||||||
|
#print ' params ', self.headers.plist
|
||||||
|
|
||||||
|
path = self.path.lower()
|
||||||
|
if path.endswith('wsdl'):
|
||||||
|
method = 'wsdl'
|
||||||
|
function = namespace = None
|
||||||
|
if self.server.funcmap.has_key(namespace) \
|
||||||
|
and self.server.funcmap[namespace].has_key(method):
|
||||||
|
function = self.server.funcmap[namespace][method]
|
||||||
|
else:
|
||||||
|
if namespace in self.server.objmap.keys():
|
||||||
|
function = self.server.objmap[namespace]
|
||||||
|
l = method.split(".")
|
||||||
|
for i in l:
|
||||||
|
function = getattr(function, i)
|
||||||
|
|
||||||
|
if function:
|
||||||
|
self.send_response(200)
|
||||||
|
self.send_header("Content-type", 'text/plain')
|
||||||
|
self.end_headers()
|
||||||
|
response = apply(function, ())
|
||||||
|
self.wfile.write(str(response))
|
||||||
|
return
|
||||||
|
|
||||||
|
# return error
|
||||||
|
self.send_response(200)
|
||||||
|
self.send_header("Content-type", 'text/html')
|
||||||
|
self.end_headers()
|
||||||
|
self.wfile.write('''\
|
||||||
|
<title>
|
||||||
|
<head>Error!</head>
|
||||||
|
</title>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
<h1>Oops!</h1>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This server supports HTTP GET requests only for the the purpose of
|
||||||
|
obtaining Web Services Description Language (WSDL) for a specific
|
||||||
|
service.
|
||||||
|
|
||||||
|
Either you requested an URL that does not end in "wsdl" or this
|
||||||
|
server does not implement a wsdl method.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
</body>''')
|
||||||
|
|
||||||
|
|
||||||
|
def log_message(self, format, *args):
|
||||||
|
if self.server.log:
|
||||||
|
BaseHTTPServer.BaseHTTPRequestHandler.\
|
||||||
|
log_message (self, format, *args)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
class SOAPServer(SOAPServerBase, SocketServer.TCPServer):
|
||||||
|
|
||||||
|
def __init__(self, addr = ('localhost', 8000),
|
||||||
|
RequestHandler = SOAPRequestHandler, log = 0, encoding = 'UTF-8',
|
||||||
|
config = Config, namespace = None, ssl_context = None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
if ssl_context != None and not config.SSLserver:
|
||||||
|
raise AttributeError, \
|
||||||
|
"SSL server not supported by this Python installation"
|
||||||
|
|
||||||
|
self.namespace = namespace
|
||||||
|
self.objmap = {}
|
||||||
|
self.funcmap = {}
|
||||||
|
self.ssl_context = ssl_context
|
||||||
|
self.encoding = encoding
|
||||||
|
self.config = config
|
||||||
|
self.log = log
|
||||||
|
|
||||||
|
self.allow_reuse_address= 1
|
||||||
|
|
||||||
|
SocketServer.TCPServer.__init__(self, addr, RequestHandler)
|
||||||
|
|
||||||
|
|
||||||
|
class ThreadingSOAPServer(SOAPServerBase, SocketServer.ThreadingTCPServer):
|
||||||
|
|
||||||
|
def __init__(self, addr = ('localhost', 8000),
|
||||||
|
RequestHandler = SOAPRequestHandler, log = 0, encoding = 'UTF-8',
|
||||||
|
config = Config, namespace = None, ssl_context = None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
if ssl_context != None and not config.SSLserver:
|
||||||
|
raise AttributeError, \
|
||||||
|
"SSL server not supported by this Python installation"
|
||||||
|
|
||||||
|
self.namespace = namespace
|
||||||
|
self.objmap = {}
|
||||||
|
self.funcmap = {}
|
||||||
|
self.ssl_context = ssl_context
|
||||||
|
self.encoding = encoding
|
||||||
|
self.config = config
|
||||||
|
self.log = log
|
||||||
|
|
||||||
|
self.allow_reuse_address= 1
|
||||||
|
|
||||||
|
SocketServer.ThreadingTCPServer.__init__(self, addr, RequestHandler)
|
||||||
|
|
||||||
|
# only define class if Unix domain sockets are available
|
||||||
|
if hasattr(socket, "AF_UNIX"):
|
||||||
|
|
||||||
|
class SOAPUnixSocketServer(SOAPServerBase, SocketServer.UnixStreamServer):
|
||||||
|
|
||||||
|
def __init__(self, addr = 8000,
|
||||||
|
RequestHandler = SOAPRequestHandler, log = 0, encoding = 'UTF-8',
|
||||||
|
config = Config, namespace = None, ssl_context = None):
|
||||||
|
|
||||||
|
# Test the encoding, raising an exception if it's not known
|
||||||
|
if encoding != None:
|
||||||
|
''.encode(encoding)
|
||||||
|
|
||||||
|
if ssl_context != None and not config.SSLserver:
|
||||||
|
raise AttributeError, \
|
||||||
|
"SSL server not supported by this Python installation"
|
||||||
|
|
||||||
|
self.namespace = namespace
|
||||||
|
self.objmap = {}
|
||||||
|
self.funcmap = {}
|
||||||
|
self.ssl_context = ssl_context
|
||||||
|
self.encoding = encoding
|
||||||
|
self.config = config
|
||||||
|
self.log = log
|
||||||
|
|
||||||
|
self.allow_reuse_address= 1
|
||||||
|
|
||||||
|
SocketServer.UnixStreamServer.__init__(self, str(addr), RequestHandler)
|
||||||
|
|
||||||
1734
others/SOAPpy/Types.py
Normal file
1734
others/SOAPpy/Types.py
Normal file
File diff suppressed because it is too large
Load Diff
23
others/SOAPpy/URLopener.py
Normal file
23
others/SOAPpy/URLopener.py
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
"""Provide a class for loading data from URL's that handles basic
|
||||||
|
authentication"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from Config import Config
|
||||||
|
from urllib import FancyURLopener
|
||||||
|
|
||||||
|
class URLopener(FancyURLopener):
|
||||||
|
|
||||||
|
username = None
|
||||||
|
passwd = None
|
||||||
|
|
||||||
|
|
||||||
|
def __init__(self, username=None, passwd=None, *args, **kw):
|
||||||
|
FancyURLopener.__init__( self, *args, **kw)
|
||||||
|
self.username = username
|
||||||
|
self.passwd = passwd
|
||||||
|
|
||||||
|
|
||||||
|
def prompt_user_passwd(self, host, realm):
|
||||||
|
return self.username, self.passwd
|
||||||
178
others/SOAPpy/Utilities.py
Normal file
178
others/SOAPpy/Utilities.py
Normal file
@ -0,0 +1,178 @@
|
|||||||
|
"""
|
||||||
|
################################################################################
|
||||||
|
# Copyright (c) 2003, Pfizer
|
||||||
|
# Copyright (c) 2001, Cayce Ullman.
|
||||||
|
# Copyright (c) 2001, Brian Matthews.
|
||||||
|
#
|
||||||
|
# All rights reserved.
|
||||||
|
#
|
||||||
|
# Redistribution and use in source and binary forms, with or without
|
||||||
|
# modification, are permitted provided that the following conditions are met:
|
||||||
|
# Redistributions of source code must retain the above copyright notice, this
|
||||||
|
# list of conditions and the following disclaimer.
|
||||||
|
#
|
||||||
|
# Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
# this list of conditions and the following disclaimer in the documentation
|
||||||
|
# and/or other materials provided with the distribution.
|
||||||
|
#
|
||||||
|
# Neither the name of actzero, inc. nor the names of its contributors may
|
||||||
|
# be used to endorse or promote products derived from this software without
|
||||||
|
# specific prior written permission.
|
||||||
|
#
|
||||||
|
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||||
|
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
||||||
|
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
#
|
||||||
|
################################################################################
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
import exceptions
|
||||||
|
import copy
|
||||||
|
import re
|
||||||
|
import string
|
||||||
|
import sys
|
||||||
|
from types import *
|
||||||
|
|
||||||
|
# SOAPpy modules
|
||||||
|
from Errors import *
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# Utility infielders
|
||||||
|
################################################################################
|
||||||
|
def collapseWhiteSpace(s):
|
||||||
|
return re.sub('\s+', ' ', s).strip()
|
||||||
|
|
||||||
|
def decodeHexString(data):
|
||||||
|
conv = {
|
||||||
|
'0': 0x0, '1': 0x1, '2': 0x2, '3': 0x3, '4': 0x4,
|
||||||
|
'5': 0x5, '6': 0x6, '7': 0x7, '8': 0x8, '9': 0x9,
|
||||||
|
|
||||||
|
'a': 0xa, 'b': 0xb, 'c': 0xc, 'd': 0xd, 'e': 0xe,
|
||||||
|
'f': 0xf,
|
||||||
|
|
||||||
|
'A': 0xa, 'B': 0xb, 'C': 0xc, 'D': 0xd, 'E': 0xe,
|
||||||
|
'F': 0xf,
|
||||||
|
}
|
||||||
|
|
||||||
|
ws = string.whitespace
|
||||||
|
|
||||||
|
bin = ''
|
||||||
|
|
||||||
|
i = 0
|
||||||
|
|
||||||
|
while i < len(data):
|
||||||
|
if data[i] not in ws:
|
||||||
|
break
|
||||||
|
i += 1
|
||||||
|
|
||||||
|
low = 0
|
||||||
|
|
||||||
|
while i < len(data):
|
||||||
|
c = data[i]
|
||||||
|
|
||||||
|
if c in string.whitespace:
|
||||||
|
break
|
||||||
|
|
||||||
|
try:
|
||||||
|
c = conv[c]
|
||||||
|
except KeyError:
|
||||||
|
raise ValueError, \
|
||||||
|
"invalid hex string character `%s'" % c
|
||||||
|
|
||||||
|
if low:
|
||||||
|
bin += chr(high * 16 + c)
|
||||||
|
low = 0
|
||||||
|
else:
|
||||||
|
high = c
|
||||||
|
low = 1
|
||||||
|
|
||||||
|
i += 1
|
||||||
|
|
||||||
|
if low:
|
||||||
|
raise ValueError, "invalid hex string length"
|
||||||
|
|
||||||
|
while i < len(data):
|
||||||
|
if data[i] not in string.whitespace:
|
||||||
|
raise ValueError, \
|
||||||
|
"invalid hex string character `%s'" % c
|
||||||
|
|
||||||
|
i += 1
|
||||||
|
|
||||||
|
return bin
|
||||||
|
|
||||||
|
def encodeHexString(data):
|
||||||
|
h = ''
|
||||||
|
|
||||||
|
for i in data:
|
||||||
|
h += "%02X" % ord(i)
|
||||||
|
|
||||||
|
return h
|
||||||
|
|
||||||
|
def leapMonth(year, month):
|
||||||
|
return month == 2 and \
|
||||||
|
year % 4 == 0 and \
|
||||||
|
(year % 100 != 0 or year % 400 == 0)
|
||||||
|
|
||||||
|
def cleanDate(d, first = 0):
|
||||||
|
ranges = (None, (1, 12), (1, 31), (0, 23), (0, 59), (0, 61))
|
||||||
|
months = (0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
|
||||||
|
names = ('year', 'month', 'day', 'hours', 'minutes', 'seconds')
|
||||||
|
|
||||||
|
if len(d) != 6:
|
||||||
|
raise ValueError, "date must have 6 elements"
|
||||||
|
|
||||||
|
for i in range(first, 6):
|
||||||
|
s = d[i]
|
||||||
|
|
||||||
|
if type(s) == FloatType:
|
||||||
|
if i < 5:
|
||||||
|
try:
|
||||||
|
s = int(s)
|
||||||
|
except OverflowError:
|
||||||
|
if i > 0:
|
||||||
|
raise
|
||||||
|
s = long(s)
|
||||||
|
|
||||||
|
if s != d[i]:
|
||||||
|
raise ValueError, "%s must be integral" % names[i]
|
||||||
|
|
||||||
|
d[i] = s
|
||||||
|
elif type(s) == LongType:
|
||||||
|
try: s = int(s)
|
||||||
|
except: pass
|
||||||
|
elif type(s) != IntType:
|
||||||
|
raise TypeError, "%s isn't a valid type" % names[i]
|
||||||
|
|
||||||
|
if i == first and s < 0:
|
||||||
|
continue
|
||||||
|
|
||||||
|
if ranges[i] != None and \
|
||||||
|
(s < ranges[i][0] or ranges[i][1] < s):
|
||||||
|
raise ValueError, "%s out of range" % names[i]
|
||||||
|
|
||||||
|
if first < 6 and d[5] >= 61:
|
||||||
|
raise ValueError, "seconds out of range"
|
||||||
|
|
||||||
|
if first < 2:
|
||||||
|
leap = first < 1 and leapMonth(d[0], d[1])
|
||||||
|
|
||||||
|
if d[2] > months[d[1]] + leap:
|
||||||
|
raise ValueError, "day out of range"
|
||||||
|
|
||||||
|
def debugHeader(title):
|
||||||
|
s = '*** ' + title + ' '
|
||||||
|
print s + ('*' * (72 - len(s)))
|
||||||
|
|
||||||
|
def debugFooter(title):
|
||||||
|
print '*' * 72
|
||||||
|
sys.stdout.flush()
|
||||||
102
others/SOAPpy/WSDL.py
Normal file
102
others/SOAPpy/WSDL.py
Normal file
@ -0,0 +1,102 @@
|
|||||||
|
"""Parse web services description language to get SOAP methods.
|
||||||
|
|
||||||
|
Rudimentary support."""
|
||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
import wstools
|
||||||
|
from Client import SOAPProxy, SOAPAddress
|
||||||
|
from Config import Config
|
||||||
|
import urllib
|
||||||
|
|
||||||
|
class Proxy:
|
||||||
|
"""WSDL Proxy.
|
||||||
|
|
||||||
|
SOAPProxy wrapper that parses method names, namespaces, soap actions from
|
||||||
|
the web service description language (WSDL) file passed into the
|
||||||
|
constructor. The WSDL reference can be passed in as a stream, an url, a
|
||||||
|
file name, or a string.
|
||||||
|
|
||||||
|
Loads info into self.methods, a dictionary with methodname keys and values
|
||||||
|
of WSDLTools.SOAPCallinfo.
|
||||||
|
|
||||||
|
For example,
|
||||||
|
|
||||||
|
url = 'http://www.xmethods.org/sd/2001/TemperatureService.wsdl'
|
||||||
|
wsdl = WSDL.Proxy(url)
|
||||||
|
print len(wsdl.methods) # 1
|
||||||
|
print wsdl.methods.keys() # getTemp
|
||||||
|
|
||||||
|
|
||||||
|
See WSDLTools.SOAPCallinfo for more info on each method's attributes.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, wsdlsource, config=Config, **kw ):
|
||||||
|
|
||||||
|
reader = wstools.WSDLTools.WSDLReader()
|
||||||
|
self.wsdl = None
|
||||||
|
|
||||||
|
# From Mark Pilgrim's "Dive Into Python" toolkit.py--open anything.
|
||||||
|
if self.wsdl is None and hasattr(wsdlsource, "read"):
|
||||||
|
#print 'stream'
|
||||||
|
self.wsdl = reader.loadFromStream(wsdlsource)
|
||||||
|
|
||||||
|
# NOT TESTED (as of April 17, 2003)
|
||||||
|
#if self.wsdl is None and wsdlsource == '-':
|
||||||
|
# import sys
|
||||||
|
# self.wsdl = reader.loadFromStream(sys.stdin)
|
||||||
|
# print 'stdin'
|
||||||
|
|
||||||
|
if self.wsdl is None:
|
||||||
|
try:
|
||||||
|
file(wsdlsource)
|
||||||
|
self.wsdl = reader.loadFromFile(wsdlsource)
|
||||||
|
#print 'file'
|
||||||
|
except (IOError, OSError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
if self.wsdl is None:
|
||||||
|
try:
|
||||||
|
stream = urllib.urlopen(wsdlsource)
|
||||||
|
self.wsdl = reader.loadFromStream(stream, wsdlsource)
|
||||||
|
except (IOError, OSError): pass
|
||||||
|
|
||||||
|
if self.wsdl is None:
|
||||||
|
import StringIO
|
||||||
|
self.wsdl = reader.loadFromString(str(wsdlsource))
|
||||||
|
#print 'string'
|
||||||
|
|
||||||
|
# Package wsdl info as a dictionary of remote methods, with method name
|
||||||
|
# as key (based on ServiceProxy.__init__ in ZSI library).
|
||||||
|
self.methods = {}
|
||||||
|
service = self.wsdl.services[0]
|
||||||
|
port = service.ports[0]
|
||||||
|
name = service.name
|
||||||
|
binding = port.getBinding()
|
||||||
|
portType = binding.getPortType()
|
||||||
|
for operation in portType.operations:
|
||||||
|
callinfo = wstools.WSDLTools.callInfoFromWSDL(port, operation.name)
|
||||||
|
self.methods[callinfo.methodName] = callinfo
|
||||||
|
|
||||||
|
self.soapproxy = SOAPProxy('http://localhost/dummy.webservice',
|
||||||
|
config=config, **kw)
|
||||||
|
|
||||||
|
def __str__(self):
|
||||||
|
s = ''
|
||||||
|
for method in self.methods.values():
|
||||||
|
s += str(method)
|
||||||
|
return s
|
||||||
|
|
||||||
|
def __getattr__(self, name):
|
||||||
|
"""Set up environment then let parent class handle call.
|
||||||
|
|
||||||
|
Raises AttributeError is method name is not found."""
|
||||||
|
|
||||||
|
if not self.methods.has_key(name): raise AttributeError, name
|
||||||
|
|
||||||
|
callinfo = self.methods[name]
|
||||||
|
self.soapproxy.proxy = SOAPAddress(callinfo.location)
|
||||||
|
self.soapproxy.namespace = callinfo.namespace
|
||||||
|
self.soapproxy.soapaction = callinfo.soapAction
|
||||||
|
return self.soapproxy.__getattr__(name)
|
||||||
15
others/SOAPpy/__init__.py
Normal file
15
others/SOAPpy/__init__.py
Normal file
@ -0,0 +1,15 @@
|
|||||||
|
|
||||||
|
ident = '$Id$'
|
||||||
|
from version import __version__
|
||||||
|
|
||||||
|
from Client import *
|
||||||
|
from Config import *
|
||||||
|
from Errors import *
|
||||||
|
from NS import *
|
||||||
|
from Parser import *
|
||||||
|
from SOAPBuilder import *
|
||||||
|
from Server import *
|
||||||
|
from Types import *
|
||||||
|
from Utilities import *
|
||||||
|
import wstools
|
||||||
|
import WSDL
|
||||||
2
others/SOAPpy/version.py
Normal file
2
others/SOAPpy/version.py
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
__version__="0.11.6"
|
||||||
|
|
||||||
91
others/SOAPpy/wstools/Namespaces.py
Executable file
91
others/SOAPpy/wstools/Namespaces.py
Executable file
@ -0,0 +1,91 @@
|
|||||||
|
"""Namespace module, so you don't need PyXML
|
||||||
|
"""
|
||||||
|
|
||||||
|
try:
|
||||||
|
from xml.ns import SOAP, SCHEMA, WSDL, XMLNS, DSIG, ENCRYPTION
|
||||||
|
except:
|
||||||
|
class SOAP:
|
||||||
|
ENV = "http://schemas.xmlsoap.org/soap/envelope/"
|
||||||
|
ENC = "http://schemas.xmlsoap.org/soap/encoding/"
|
||||||
|
ACTOR_NEXT = "http://schemas.xmlsoap.org/soap/actor/next"
|
||||||
|
|
||||||
|
class SCHEMA:
|
||||||
|
XSD1 = "http://www.w3.org/1999/XMLSchema"
|
||||||
|
XSD2 = "http://www.w3.org/2000/10/XMLSchema"
|
||||||
|
XSD3 = "http://www.w3.org/2001/XMLSchema"
|
||||||
|
XSD_LIST = [ XSD1, XSD2, XSD3 ]
|
||||||
|
XSI1 = "http://www.w3.org/1999/XMLSchema-instance"
|
||||||
|
XSI2 = "http://www.w3.org/2000/10/XMLSchema-instance"
|
||||||
|
XSI3 = "http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
XSI_LIST = [ XSI1, XSI2, XSI3 ]
|
||||||
|
BASE = XSD3
|
||||||
|
|
||||||
|
class WSDL:
|
||||||
|
BASE = "http://schemas.xmlsoap.org/wsdl/"
|
||||||
|
BIND_HTTP = "http://schemas.xmlsoap.org/wsdl/http/"
|
||||||
|
BIND_MIME = "http://schemas.xmlsoap.org/wsdl/mime/"
|
||||||
|
BIND_SOAP = "http://schemas.xmlsoap.org/wsdl/soap/"
|
||||||
|
|
||||||
|
class XMLNS:
|
||||||
|
BASE = "http://www.w3.org/2000/xmlns/"
|
||||||
|
XML = "http://www.w3.org/XML/1998/namespace"
|
||||||
|
HTML = "http://www.w3.org/TR/REC-html40"
|
||||||
|
|
||||||
|
class DSIG:
|
||||||
|
BASE = "http://www.w3.org/2000/09/xmldsig#"
|
||||||
|
C14N = "http://www.w3.org/TR/2000/CR-xml-c14n-20010315"
|
||||||
|
C14N_COMM = "http://www.w3.org/TR/2000/CR-xml-c14n-20010315#WithComments"
|
||||||
|
C14N_EXCL = "http://www.w3.org/2001/10/xml-exc-c14n#"
|
||||||
|
DIGEST_MD2 = "http://www.w3.org/2000/09/xmldsig#md2"
|
||||||
|
DIGEST_MD5 = "http://www.w3.org/2000/09/xmldsig#md5"
|
||||||
|
DIGEST_SHA1 = "http://www.w3.org/2000/09/xmldsig#sha1"
|
||||||
|
ENC_BASE64 = "http://www.w3.org/2000/09/xmldsig#base64"
|
||||||
|
ENVELOPED = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
|
||||||
|
HMAC_SHA1 = "http://www.w3.org/2000/09/xmldsig#hmac-sha1"
|
||||||
|
SIG_DSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#dsa-sha1"
|
||||||
|
SIG_RSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
|
||||||
|
XPATH = "http://www.w3.org/TR/1999/REC-xpath-19991116"
|
||||||
|
XSLT = "http://www.w3.org/TR/1999/REC-xslt-19991116"
|
||||||
|
|
||||||
|
class ENCRYPTION:
|
||||||
|
BASE = "http://www.w3.org/2001/04/xmlenc#"
|
||||||
|
BLOCK_3DES = "http://www.w3.org/2001/04/xmlenc#des-cbc"
|
||||||
|
BLOCK_AES128 = "http://www.w3.org/2001/04/xmlenc#aes128-cbc"
|
||||||
|
BLOCK_AES192 = "http://www.w3.org/2001/04/xmlenc#aes192-cbc"
|
||||||
|
BLOCK_AES256 = "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
|
||||||
|
DIGEST_RIPEMD160 = "http://www.w3.org/2001/04/xmlenc#ripemd160"
|
||||||
|
DIGEST_SHA256 = "http://www.w3.org/2001/04/xmlenc#sha256"
|
||||||
|
DIGEST_SHA512 = "http://www.w3.org/2001/04/xmlenc#sha512"
|
||||||
|
KA_DH = "http://www.w3.org/2001/04/xmlenc#dh"
|
||||||
|
KT_RSA_1_5 = "http://www.w3.org/2001/04/xmlenc#rsa-1_5"
|
||||||
|
KT_RSA_OAEP = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
|
||||||
|
STREAM_ARCFOUR = "http://www.w3.org/2001/04/xmlenc#arcfour"
|
||||||
|
WRAP_3DES = "http://www.w3.org/2001/04/xmlenc#kw-3des"
|
||||||
|
WRAP_AES128 = "http://www.w3.org/2001/04/xmlenc#kw-aes128"
|
||||||
|
WRAP_AES192 = "http://www.w3.org/2001/04/xmlenc#kw-aes192"
|
||||||
|
WRAP_AES256 = "http://www.w3.org/2001/04/xmlenc#kw-aes256"
|
||||||
|
|
||||||
|
|
||||||
|
class WSSE:
|
||||||
|
BASE = "http://schemas.xmlsoap.org/ws/2002/04/secext"
|
||||||
|
|
||||||
|
class WSU:
|
||||||
|
BASE = "http://schemas.xmlsoap.org/ws/2002/04/utility"
|
||||||
|
UTILITY = "http://schemas.xmlsoap.org/ws/2002/07/utility"
|
||||||
|
|
||||||
|
class WSR:
|
||||||
|
PROPERTIES = "http://www.ibm.com/xmlns/stdwip/web-services/WS-ResourceProperties"
|
||||||
|
LIFETIME = "http://www.ibm.com/xmlns/stdwip/web-services/WS-ResourceLifetime"
|
||||||
|
|
||||||
|
class WSA:
|
||||||
|
ADDRESS = "http://schemas.xmlsoap.org/ws/2003/03/addressing"
|
||||||
|
ADDRESS2004 = "http://schemas.xmlsoap.org/ws/2004/03/addressing"
|
||||||
|
ANONYMOUS = "%s/role/anonymous" %ADDRESS
|
||||||
|
ANONYMOUS2004 = "%s/role/anonymous" %ADDRESS2004
|
||||||
|
FAULT = "http://schemas.xmlsoap.org/ws/2004/03/addressing/fault"
|
||||||
|
|
||||||
|
class WSP:
|
||||||
|
POLICY = "http://schemas.xmlsoap.org/ws/2002/12/policy"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
179
others/SOAPpy/wstools/TimeoutSocket.py
Executable file
179
others/SOAPpy/wstools/TimeoutSocket.py
Executable file
@ -0,0 +1,179 @@
|
|||||||
|
"""Based on code from timeout_socket.py, with some tweaks for compatibility.
|
||||||
|
These tweaks should really be rolled back into timeout_socket, but it's
|
||||||
|
not totally clear who is maintaining it at this point. In the meantime,
|
||||||
|
we'll use a different module name for our tweaked version to avoid any
|
||||||
|
confusion.
|
||||||
|
|
||||||
|
The original timeout_socket is by:
|
||||||
|
|
||||||
|
Scott Cotton <scott@chronis.pobox.com>
|
||||||
|
Lloyd Zusman <ljz@asfast.com>
|
||||||
|
Phil Mayes <pmayes@olivebr.com>
|
||||||
|
Piers Lauder <piers@cs.su.oz.au>
|
||||||
|
Radovan Garabik <garabik@melkor.dnp.fmph.uniba.sk>
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = "$Id$"
|
||||||
|
|
||||||
|
import string, socket, select, errno
|
||||||
|
|
||||||
|
WSAEINVAL = getattr(errno, 'WSAEINVAL', 10022)
|
||||||
|
|
||||||
|
|
||||||
|
class TimeoutSocket:
|
||||||
|
"""A socket imposter that supports timeout limits."""
|
||||||
|
|
||||||
|
def __init__(self, timeout=20, sock=None):
|
||||||
|
self.timeout = float(timeout)
|
||||||
|
self.inbuf = ''
|
||||||
|
if sock is None:
|
||||||
|
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||||
|
self.sock = sock
|
||||||
|
self.sock.setblocking(0)
|
||||||
|
self._rbuf = ''
|
||||||
|
self._wbuf = ''
|
||||||
|
|
||||||
|
def __getattr__(self, name):
|
||||||
|
# Delegate to real socket attributes.
|
||||||
|
return getattr(self.sock, name)
|
||||||
|
|
||||||
|
def connect(self, *addr):
|
||||||
|
timeout = self.timeout
|
||||||
|
sock = self.sock
|
||||||
|
try:
|
||||||
|
# Non-blocking mode
|
||||||
|
sock.setblocking(0)
|
||||||
|
apply(sock.connect, addr)
|
||||||
|
sock.setblocking(timeout != 0)
|
||||||
|
return 1
|
||||||
|
except socket.error,why:
|
||||||
|
if not timeout:
|
||||||
|
raise
|
||||||
|
sock.setblocking(1)
|
||||||
|
if len(why.args) == 1:
|
||||||
|
code = 0
|
||||||
|
else:
|
||||||
|
code, why = why
|
||||||
|
if code not in (
|
||||||
|
errno.EINPROGRESS, errno.EALREADY, errno.EWOULDBLOCK
|
||||||
|
):
|
||||||
|
raise
|
||||||
|
r,w,e = select.select([],[sock],[],timeout)
|
||||||
|
if w:
|
||||||
|
try:
|
||||||
|
apply(sock.connect, addr)
|
||||||
|
return 1
|
||||||
|
except socket.error,why:
|
||||||
|
if len(why.args) == 1:
|
||||||
|
code = 0
|
||||||
|
else:
|
||||||
|
code, why = why
|
||||||
|
if code in (errno.EISCONN, WSAEINVAL):
|
||||||
|
return 1
|
||||||
|
raise
|
||||||
|
raise TimeoutError('socket connect() timeout.')
|
||||||
|
|
||||||
|
def send(self, data, flags=0):
|
||||||
|
total = len(data)
|
||||||
|
next = 0
|
||||||
|
while 1:
|
||||||
|
r, w, e = select.select([],[self.sock], [], self.timeout)
|
||||||
|
if w:
|
||||||
|
buff = data[next:next + 8192]
|
||||||
|
sent = self.sock.send(buff, flags)
|
||||||
|
next = next + sent
|
||||||
|
if next == total:
|
||||||
|
return total
|
||||||
|
continue
|
||||||
|
raise TimeoutError('socket send() timeout.')
|
||||||
|
|
||||||
|
def recv(self, amt, flags=0):
|
||||||
|
if select.select([self.sock], [], [], self.timeout)[0]:
|
||||||
|
return self.sock.recv(amt, flags)
|
||||||
|
raise TimeoutError('socket recv() timeout.')
|
||||||
|
|
||||||
|
buffsize = 4096
|
||||||
|
handles = 1
|
||||||
|
|
||||||
|
def makefile(self, mode="r", buffsize=-1):
|
||||||
|
self.handles = self.handles + 1
|
||||||
|
self.mode = mode
|
||||||
|
return self
|
||||||
|
|
||||||
|
def close(self):
|
||||||
|
self.handles = self.handles - 1
|
||||||
|
if self.handles == 0 and self.sock.fileno() >= 0:
|
||||||
|
self.sock.close()
|
||||||
|
|
||||||
|
def read(self, n=-1):
|
||||||
|
if not isinstance(n, type(1)):
|
||||||
|
n = -1
|
||||||
|
if n >= 0:
|
||||||
|
k = len(self._rbuf)
|
||||||
|
if n <= k:
|
||||||
|
data = self._rbuf[:n]
|
||||||
|
self._rbuf = self._rbuf[n:]
|
||||||
|
return data
|
||||||
|
n = n - k
|
||||||
|
L = [self._rbuf]
|
||||||
|
self._rbuf = ""
|
||||||
|
while n > 0:
|
||||||
|
new = self.recv(max(n, self.buffsize))
|
||||||
|
if not new: break
|
||||||
|
k = len(new)
|
||||||
|
if k > n:
|
||||||
|
L.append(new[:n])
|
||||||
|
self._rbuf = new[n:]
|
||||||
|
break
|
||||||
|
L.append(new)
|
||||||
|
n = n - k
|
||||||
|
return "".join(L)
|
||||||
|
k = max(4096, self.buffsize)
|
||||||
|
L = [self._rbuf]
|
||||||
|
self._rbuf = ""
|
||||||
|
while 1:
|
||||||
|
new = self.recv(k)
|
||||||
|
if not new: break
|
||||||
|
L.append(new)
|
||||||
|
k = min(k*2, 1024**2)
|
||||||
|
return "".join(L)
|
||||||
|
|
||||||
|
def readline(self, limit=-1):
|
||||||
|
data = ""
|
||||||
|
i = self._rbuf.find('\n')
|
||||||
|
while i < 0 and not (0 < limit <= len(self._rbuf)):
|
||||||
|
new = self.recv(self.buffsize)
|
||||||
|
if not new: break
|
||||||
|
i = new.find('\n')
|
||||||
|
if i >= 0: i = i + len(self._rbuf)
|
||||||
|
self._rbuf = self._rbuf + new
|
||||||
|
if i < 0: i = len(self._rbuf)
|
||||||
|
else: i = i+1
|
||||||
|
if 0 <= limit < len(self._rbuf): i = limit
|
||||||
|
data, self._rbuf = self._rbuf[:i], self._rbuf[i:]
|
||||||
|
return data
|
||||||
|
|
||||||
|
def readlines(self, sizehint = 0):
|
||||||
|
total = 0
|
||||||
|
list = []
|
||||||
|
while 1:
|
||||||
|
line = self.readline()
|
||||||
|
if not line: break
|
||||||
|
list.append(line)
|
||||||
|
total += len(line)
|
||||||
|
if sizehint and total >= sizehint:
|
||||||
|
break
|
||||||
|
return list
|
||||||
|
|
||||||
|
def writelines(self, list):
|
||||||
|
self.send(''.join(list))
|
||||||
|
|
||||||
|
def write(self, data):
|
||||||
|
self.send(data)
|
||||||
|
|
||||||
|
def flush(self):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class TimeoutError(Exception):
|
||||||
|
pass
|
||||||
99
others/SOAPpy/wstools/UserTuple.py
Executable file
99
others/SOAPpy/wstools/UserTuple.py
Executable file
@ -0,0 +1,99 @@
|
|||||||
|
"""
|
||||||
|
A more or less complete user-defined wrapper around tuple objects.
|
||||||
|
Adapted version of the standard library's UserList.
|
||||||
|
|
||||||
|
Taken from Stefan Schwarzer's ftputil library, available at
|
||||||
|
<http://www.ndh.net/home/sschwarzer/python/python_software.html>, and used under this license:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Copyright (C) 1999, Stefan Schwarzer
|
||||||
|
All rights reserved.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without
|
||||||
|
modification, are permitted provided that the following conditions are
|
||||||
|
met:
|
||||||
|
|
||||||
|
- Redistributions of source code must retain the above copyright
|
||||||
|
notice, this list of conditions and the following disclaimer.
|
||||||
|
|
||||||
|
- Redistributions in binary form must reproduce the above copyright
|
||||||
|
notice, this list of conditions and the following disclaimer in the
|
||||||
|
documentation and/or other materials provided with the distribution.
|
||||||
|
|
||||||
|
- Neither the name of the above author nor the names of the
|
||||||
|
contributors to the software may be used to endorse or promote
|
||||||
|
products derived from this software without specific prior written
|
||||||
|
permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||||
|
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||||
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||||||
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
|
||||||
|
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
||||||
|
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
||||||
|
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
||||||
|
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
||||||
|
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
||||||
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# $Id$
|
||||||
|
|
||||||
|
#XXX tuple instances (in Python 2.2) contain also:
|
||||||
|
# __class__, __delattr__, __getattribute__, __hash__, __new__,
|
||||||
|
# __reduce__, __setattr__, __str__
|
||||||
|
# What about these?
|
||||||
|
|
||||||
|
class UserTuple:
|
||||||
|
def __init__(self, inittuple=None):
|
||||||
|
self.data = ()
|
||||||
|
if inittuple is not None:
|
||||||
|
# XXX should this accept an arbitrary sequence?
|
||||||
|
if type(inittuple) == type(self.data):
|
||||||
|
self.data = inittuple
|
||||||
|
elif isinstance(inittuple, UserTuple):
|
||||||
|
# this results in
|
||||||
|
# self.data is inittuple.data
|
||||||
|
# but that's ok for tuples because they are
|
||||||
|
# immutable. (Builtin tuples behave the same.)
|
||||||
|
self.data = inittuple.data[:]
|
||||||
|
else:
|
||||||
|
# the same applies here; (t is tuple(t)) == 1
|
||||||
|
self.data = tuple(inittuple)
|
||||||
|
def __repr__(self): return repr(self.data)
|
||||||
|
def __lt__(self, other): return self.data < self.__cast(other)
|
||||||
|
def __le__(self, other): return self.data <= self.__cast(other)
|
||||||
|
def __eq__(self, other): return self.data == self.__cast(other)
|
||||||
|
def __ne__(self, other): return self.data != self.__cast(other)
|
||||||
|
def __gt__(self, other): return self.data > self.__cast(other)
|
||||||
|
def __ge__(self, other): return self.data >= self.__cast(other)
|
||||||
|
def __cast(self, other):
|
||||||
|
if isinstance(other, UserTuple): return other.data
|
||||||
|
else: return other
|
||||||
|
def __cmp__(self, other):
|
||||||
|
return cmp(self.data, self.__cast(other))
|
||||||
|
def __contains__(self, item): return item in self.data
|
||||||
|
def __len__(self): return len(self.data)
|
||||||
|
def __getitem__(self, i): return self.data[i]
|
||||||
|
def __getslice__(self, i, j):
|
||||||
|
i = max(i, 0); j = max(j, 0)
|
||||||
|
return self.__class__(self.data[i:j])
|
||||||
|
def __add__(self, other):
|
||||||
|
if isinstance(other, UserTuple):
|
||||||
|
return self.__class__(self.data + other.data)
|
||||||
|
elif isinstance(other, type(self.data)):
|
||||||
|
return self.__class__(self.data + other)
|
||||||
|
else:
|
||||||
|
return self.__class__(self.data + tuple(other))
|
||||||
|
# dir( () ) contains no __radd__ (at least in Python 2.2)
|
||||||
|
def __mul__(self, n):
|
||||||
|
return self.__class__(self.data*n)
|
||||||
|
__rmul__ = __mul__
|
||||||
|
|
||||||
839
others/SOAPpy/wstools/Utility.py
Executable file
839
others/SOAPpy/wstools/Utility.py
Executable file
@ -0,0 +1,839 @@
|
|||||||
|
# Copyright (c) 2001 Zope Corporation and Contributors. All Rights Reserved.
|
||||||
|
#
|
||||||
|
# This software is subject to the provisions of the Zope Public License,
|
||||||
|
# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
|
||||||
|
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
|
||||||
|
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||||
|
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
|
||||||
|
# FOR A PARTICULAR PURPOSE.
|
||||||
|
|
||||||
|
ident = "$Id$"
|
||||||
|
|
||||||
|
import types
|
||||||
|
import string, httplib, smtplib, urllib, socket, weakref
|
||||||
|
import xml.dom.minidom
|
||||||
|
from string import join, strip, split
|
||||||
|
from UserDict import UserDict
|
||||||
|
from StringIO import StringIO
|
||||||
|
from TimeoutSocket import TimeoutSocket, TimeoutError
|
||||||
|
from urlparse import urlparse
|
||||||
|
from httplib import HTTPConnection, HTTPSConnection
|
||||||
|
from exceptions import Exception
|
||||||
|
|
||||||
|
try:
|
||||||
|
from xml.dom.ext import SplitQName
|
||||||
|
except:
|
||||||
|
def SplitQName(qname):
|
||||||
|
'''SplitQName(qname) -> (string, string)
|
||||||
|
|
||||||
|
Split Qualified Name into a tuple of len 2, consisting
|
||||||
|
of the prefix and the local name.
|
||||||
|
|
||||||
|
(prefix, localName)
|
||||||
|
|
||||||
|
Special Cases:
|
||||||
|
xmlns -- (localName, 'xmlns')
|
||||||
|
None -- (None, localName)
|
||||||
|
'''
|
||||||
|
|
||||||
|
l = qname.split(':')
|
||||||
|
if len(l) == 1:
|
||||||
|
l.insert(0, None)
|
||||||
|
elif len(l) == 2:
|
||||||
|
if l[0] == 'xmlns':
|
||||||
|
l.reverse()
|
||||||
|
else:
|
||||||
|
return
|
||||||
|
return tuple(l)
|
||||||
|
|
||||||
|
class RecursionError(Exception):
|
||||||
|
"""Used to indicate a HTTP redirect recursion."""
|
||||||
|
pass
|
||||||
|
|
||||||
|
class HTTPResponse:
|
||||||
|
"""Captures the information in an HTTP response message."""
|
||||||
|
|
||||||
|
def __init__(self, response):
|
||||||
|
self.status = response.status
|
||||||
|
self.reason = response.reason
|
||||||
|
self.headers = response.msg
|
||||||
|
self.body = response.read() or None
|
||||||
|
response.close()
|
||||||
|
|
||||||
|
class TimeoutHTTP(HTTPConnection):
|
||||||
|
"""A custom http connection object that supports socket timeout."""
|
||||||
|
def __init__(self, host, port=None, timeout=20):
|
||||||
|
HTTPConnection.__init__(self, host, port)
|
||||||
|
self.timeout = timeout
|
||||||
|
|
||||||
|
def connect(self):
|
||||||
|
self.sock = TimeoutSocket(self.timeout)
|
||||||
|
self.sock.connect((self.host, self.port))
|
||||||
|
|
||||||
|
|
||||||
|
class TimeoutHTTPS(HTTPSConnection):
|
||||||
|
"""A custom https object that supports socket timeout. Note that this
|
||||||
|
is not really complete. The builtin SSL support in the Python socket
|
||||||
|
module requires a real socket (type) to be passed in to be hooked to
|
||||||
|
SSL. That means our fake socket won't work and our timeout hacks are
|
||||||
|
bypassed for send and recv calls. Since our hack _is_ in place at
|
||||||
|
connect() time, it should at least provide some timeout protection."""
|
||||||
|
def __init__(self, host, port=None, timeout=20, **kwargs):
|
||||||
|
HTTPSConnection.__init__(self, str(host), port, **kwargs)
|
||||||
|
self.timeout = timeout
|
||||||
|
|
||||||
|
def connect(self):
|
||||||
|
sock = TimeoutSocket(self.timeout)
|
||||||
|
sock.connect((self.host, self.port))
|
||||||
|
realsock = getattr(sock.sock, '_sock', sock.sock)
|
||||||
|
ssl = socket.ssl(realsock, self.key_file, self.cert_file)
|
||||||
|
self.sock = httplib.FakeSocket(sock, ssl)
|
||||||
|
|
||||||
|
def urlopen(url, timeout=20, redirects=None):
|
||||||
|
"""A minimal urlopen replacement hack that supports timeouts for http.
|
||||||
|
Note that this supports GET only."""
|
||||||
|
scheme, host, path, params, query, frag = urlparse(url)
|
||||||
|
if not scheme in ('http', 'https'):
|
||||||
|
return urllib.urlopen(url)
|
||||||
|
if params: path = '%s;%s' % (path, params)
|
||||||
|
if query: path = '%s?%s' % (path, query)
|
||||||
|
if frag: path = '%s#%s' % (path, frag)
|
||||||
|
|
||||||
|
if scheme == 'https':
|
||||||
|
# If ssl is not compiled into Python, you will not get an exception
|
||||||
|
# until a conn.endheaders() call. We need to know sooner, so use
|
||||||
|
# getattr.
|
||||||
|
if hasattr(socket, 'ssl'):
|
||||||
|
conn = TimeoutHTTPS(host, None, timeout)
|
||||||
|
else:
|
||||||
|
import M2Crypto
|
||||||
|
ctx = M2Crypto.SSL.Context()
|
||||||
|
ctx.set_session_timeout(timeout)
|
||||||
|
conn = M2Crypto.httpslib.HTTPSConnection(host, ssl_context=ctx)
|
||||||
|
#conn.set_debuglevel(1)
|
||||||
|
else:
|
||||||
|
conn = TimeoutHTTP(host, None, timeout)
|
||||||
|
|
||||||
|
conn.putrequest('GET', path)
|
||||||
|
conn.putheader('Connection', 'close')
|
||||||
|
conn.endheaders()
|
||||||
|
response = None
|
||||||
|
while 1:
|
||||||
|
response = conn.getresponse()
|
||||||
|
if response.status != 100:
|
||||||
|
break
|
||||||
|
conn._HTTPConnection__state = httplib._CS_REQ_SENT
|
||||||
|
conn._HTTPConnection__response = None
|
||||||
|
|
||||||
|
status = response.status
|
||||||
|
|
||||||
|
# If we get an HTTP redirect, we will follow it automatically.
|
||||||
|
if status >= 300 and status < 400:
|
||||||
|
location = response.msg.getheader('location')
|
||||||
|
if location is not None:
|
||||||
|
response.close()
|
||||||
|
if redirects is not None and redirects.has_key(location):
|
||||||
|
raise RecursionError(
|
||||||
|
'Circular HTTP redirection detected.'
|
||||||
|
)
|
||||||
|
if redirects is None:
|
||||||
|
redirects = {}
|
||||||
|
redirects[location] = 1
|
||||||
|
return urlopen(location, timeout, redirects)
|
||||||
|
raise HTTPResponse(response)
|
||||||
|
|
||||||
|
if not (status >= 200 and status < 300):
|
||||||
|
raise HTTPResponse(response)
|
||||||
|
|
||||||
|
body = StringIO(response.read())
|
||||||
|
response.close()
|
||||||
|
return body
|
||||||
|
|
||||||
|
class DOM:
|
||||||
|
"""The DOM singleton defines a number of XML related constants and
|
||||||
|
provides a number of utility methods for DOM related tasks. It
|
||||||
|
also provides some basic abstractions so that the rest of the
|
||||||
|
package need not care about actual DOM implementation in use."""
|
||||||
|
|
||||||
|
# Namespace stuff related to the SOAP specification.
|
||||||
|
|
||||||
|
NS_SOAP_ENV_1_1 = 'http://schemas.xmlsoap.org/soap/envelope/'
|
||||||
|
NS_SOAP_ENC_1_1 = 'http://schemas.xmlsoap.org/soap/encoding/'
|
||||||
|
|
||||||
|
NS_SOAP_ENV_1_2 = 'http://www.w3.org/2001/06/soap-envelope'
|
||||||
|
NS_SOAP_ENC_1_2 = 'http://www.w3.org/2001/06/soap-encoding'
|
||||||
|
|
||||||
|
NS_SOAP_ENV_ALL = (NS_SOAP_ENV_1_1, NS_SOAP_ENV_1_2)
|
||||||
|
NS_SOAP_ENC_ALL = (NS_SOAP_ENC_1_1, NS_SOAP_ENC_1_2)
|
||||||
|
|
||||||
|
NS_SOAP_ENV = NS_SOAP_ENV_1_1
|
||||||
|
NS_SOAP_ENC = NS_SOAP_ENC_1_1
|
||||||
|
|
||||||
|
_soap_uri_mapping = {
|
||||||
|
NS_SOAP_ENV_1_1 : '1.1',
|
||||||
|
NS_SOAP_ENV_1_2 : '1.2',
|
||||||
|
}
|
||||||
|
|
||||||
|
SOAP_ACTOR_NEXT_1_1 = 'http://schemas.xmlsoap.org/soap/actor/next'
|
||||||
|
SOAP_ACTOR_NEXT_1_2 = 'http://www.w3.org/2001/06/soap-envelope/actor/next'
|
||||||
|
SOAP_ACTOR_NEXT_ALL = (SOAP_ACTOR_NEXT_1_1, SOAP_ACTOR_NEXT_1_2)
|
||||||
|
|
||||||
|
def SOAPUriToVersion(self, uri):
|
||||||
|
"""Return the SOAP version related to an envelope uri."""
|
||||||
|
value = self._soap_uri_mapping.get(uri)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported SOAP envelope uri: %s' % uri
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetSOAPEnvUri(self, version):
|
||||||
|
"""Return the appropriate SOAP envelope uri for a given
|
||||||
|
human-friendly SOAP version string (e.g. '1.1')."""
|
||||||
|
attrname = 'NS_SOAP_ENV_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attrname, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported SOAP version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetSOAPEncUri(self, version):
|
||||||
|
"""Return the appropriate SOAP encoding uri for a given
|
||||||
|
human-friendly SOAP version string (e.g. '1.1')."""
|
||||||
|
attrname = 'NS_SOAP_ENC_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attrname, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported SOAP version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetSOAPActorNextUri(self, version):
|
||||||
|
"""Return the right special next-actor uri for a given
|
||||||
|
human-friendly SOAP version string (e.g. '1.1')."""
|
||||||
|
attrname = 'SOAP_ACTOR_NEXT_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attrname, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported SOAP version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# Namespace stuff related to XML Schema.
|
||||||
|
|
||||||
|
NS_XSD_99 = 'http://www.w3.org/1999/XMLSchema'
|
||||||
|
NS_XSI_99 = 'http://www.w3.org/1999/XMLSchema-instance'
|
||||||
|
|
||||||
|
NS_XSD_00 = 'http://www.w3.org/2000/10/XMLSchema'
|
||||||
|
NS_XSI_00 = 'http://www.w3.org/2000/10/XMLSchema-instance'
|
||||||
|
|
||||||
|
NS_XSD_01 = 'http://www.w3.org/2001/XMLSchema'
|
||||||
|
NS_XSI_01 = 'http://www.w3.org/2001/XMLSchema-instance'
|
||||||
|
|
||||||
|
NS_XSD_ALL = (NS_XSD_99, NS_XSD_00, NS_XSD_01)
|
||||||
|
NS_XSI_ALL = (NS_XSI_99, NS_XSI_00, NS_XSI_01)
|
||||||
|
|
||||||
|
NS_XSD = NS_XSD_01
|
||||||
|
NS_XSI = NS_XSI_01
|
||||||
|
|
||||||
|
_xsd_uri_mapping = {
|
||||||
|
NS_XSD_99 : NS_XSI_99,
|
||||||
|
NS_XSD_00 : NS_XSI_00,
|
||||||
|
NS_XSD_01 : NS_XSI_01,
|
||||||
|
}
|
||||||
|
|
||||||
|
for key, value in _xsd_uri_mapping.items():
|
||||||
|
_xsd_uri_mapping[value] = key
|
||||||
|
|
||||||
|
|
||||||
|
def InstanceUriForSchemaUri(self, uri):
|
||||||
|
"""Return the appropriate matching XML Schema instance uri for
|
||||||
|
the given XML Schema namespace uri."""
|
||||||
|
return self._xsd_uri_mapping.get(uri)
|
||||||
|
|
||||||
|
def SchemaUriForInstanceUri(self, uri):
|
||||||
|
"""Return the appropriate matching XML Schema namespace uri for
|
||||||
|
the given XML Schema instance namespace uri."""
|
||||||
|
return self._xsd_uri_mapping.get(uri)
|
||||||
|
|
||||||
|
|
||||||
|
# Namespace stuff related to WSDL.
|
||||||
|
|
||||||
|
NS_WSDL_1_1 = 'http://schemas.xmlsoap.org/wsdl/'
|
||||||
|
NS_WSDL_ALL = (NS_WSDL_1_1,)
|
||||||
|
NS_WSDL = NS_WSDL_1_1
|
||||||
|
|
||||||
|
NS_SOAP_BINDING_1_1 = 'http://schemas.xmlsoap.org/wsdl/soap/'
|
||||||
|
NS_HTTP_BINDING_1_1 = 'http://schemas.xmlsoap.org/wsdl/http/'
|
||||||
|
NS_MIME_BINDING_1_1 = 'http://schemas.xmlsoap.org/wsdl/mime/'
|
||||||
|
|
||||||
|
NS_SOAP_BINDING_ALL = (NS_SOAP_BINDING_1_1,)
|
||||||
|
NS_HTTP_BINDING_ALL = (NS_HTTP_BINDING_1_1,)
|
||||||
|
NS_MIME_BINDING_ALL = (NS_MIME_BINDING_1_1,)
|
||||||
|
|
||||||
|
NS_SOAP_BINDING = NS_SOAP_BINDING_1_1
|
||||||
|
NS_HTTP_BINDING = NS_HTTP_BINDING_1_1
|
||||||
|
NS_MIME_BINDING = NS_MIME_BINDING_1_1
|
||||||
|
|
||||||
|
NS_SOAP_HTTP_1_1 = 'http://schemas.xmlsoap.org/soap/http'
|
||||||
|
NS_SOAP_HTTP_ALL = (NS_SOAP_HTTP_1_1,)
|
||||||
|
NS_SOAP_HTTP = NS_SOAP_HTTP_1_1
|
||||||
|
|
||||||
|
|
||||||
|
_wsdl_uri_mapping = {
|
||||||
|
NS_WSDL_1_1 : '1.1',
|
||||||
|
}
|
||||||
|
|
||||||
|
def WSDLUriToVersion(self, uri):
|
||||||
|
"""Return the WSDL version related to a WSDL namespace uri."""
|
||||||
|
value = self._wsdl_uri_mapping.get(uri)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported SOAP envelope uri: %s' % uri
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetWSDLUri(self, version):
|
||||||
|
attr = 'NS_WSDL_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attr, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported WSDL version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetWSDLSoapBindingUri(self, version):
|
||||||
|
attr = 'NS_SOAP_BINDING_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attr, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported WSDL version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetWSDLHttpBindingUri(self, version):
|
||||||
|
attr = 'NS_HTTP_BINDING_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attr, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported WSDL version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetWSDLMimeBindingUri(self, version):
|
||||||
|
attr = 'NS_MIME_BINDING_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attr, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported WSDL version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
def GetWSDLHttpTransportUri(self, version):
|
||||||
|
attr = 'NS_SOAP_HTTP_%s' % join(split(version, '.'), '_')
|
||||||
|
value = getattr(self, attr, None)
|
||||||
|
if value is not None:
|
||||||
|
return value
|
||||||
|
raise ValueError(
|
||||||
|
'Unsupported WSDL version: %s' % version
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# Other xml namespace constants.
|
||||||
|
NS_XMLNS = 'http://www.w3.org/2000/xmlns/'
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
def isElement(self, node, name, nsuri=None):
|
||||||
|
"""Return true if the given node is an element with the given
|
||||||
|
name and optional namespace uri."""
|
||||||
|
if node.nodeType != node.ELEMENT_NODE:
|
||||||
|
return 0
|
||||||
|
return node.localName == name and \
|
||||||
|
(nsuri is None or self.nsUriMatch(node.namespaceURI, nsuri))
|
||||||
|
|
||||||
|
def getElement(self, node, name, nsuri=None, default=join):
|
||||||
|
"""Return the first child of node with a matching name and
|
||||||
|
namespace uri, or the default if one is provided."""
|
||||||
|
nsmatch = self.nsUriMatch
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
for child in node.childNodes:
|
||||||
|
if child.nodeType == ELEMENT_NODE:
|
||||||
|
if ((child.localName == name or name is None) and
|
||||||
|
(nsuri is None or nsmatch(child.namespaceURI, nsuri))
|
||||||
|
):
|
||||||
|
return child
|
||||||
|
if default is not join:
|
||||||
|
return default
|
||||||
|
raise KeyError, name
|
||||||
|
|
||||||
|
def getElementById(self, node, id, default=join):
|
||||||
|
"""Return the first child of node matching an id reference."""
|
||||||
|
attrget = self.getAttr
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
for child in node.childNodes:
|
||||||
|
if child.nodeType == ELEMENT_NODE:
|
||||||
|
if attrget(child, 'id') == id:
|
||||||
|
return child
|
||||||
|
if default is not join:
|
||||||
|
return default
|
||||||
|
raise KeyError, name
|
||||||
|
|
||||||
|
def getMappingById(self, document, depth=None, element=None,
|
||||||
|
mapping=None, level=1):
|
||||||
|
"""Create an id -> element mapping of those elements within a
|
||||||
|
document that define an id attribute. The depth of the search
|
||||||
|
may be controlled by using the (1-based) depth argument."""
|
||||||
|
if document is not None:
|
||||||
|
element = document.documentElement
|
||||||
|
mapping = {}
|
||||||
|
attr = element._attrs.get('id', None)
|
||||||
|
if attr is not None:
|
||||||
|
mapping[attr.value] = element
|
||||||
|
if depth is None or depth > level:
|
||||||
|
level = level + 1
|
||||||
|
ELEMENT_NODE = element.ELEMENT_NODE
|
||||||
|
for child in element.childNodes:
|
||||||
|
if child.nodeType == ELEMENT_NODE:
|
||||||
|
self.getMappingById(None, depth, child, mapping, level)
|
||||||
|
return mapping
|
||||||
|
|
||||||
|
def getElements(self, node, name, nsuri=None):
|
||||||
|
"""Return a sequence of the child elements of the given node that
|
||||||
|
match the given name and optional namespace uri."""
|
||||||
|
nsmatch = self.nsUriMatch
|
||||||
|
result = []
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
for child in node.childNodes:
|
||||||
|
if child.nodeType == ELEMENT_NODE:
|
||||||
|
if ((child.localName == name or name is None) and (
|
||||||
|
(nsuri is None) or nsmatch(child.namespaceURI, nsuri))):
|
||||||
|
result.append(child)
|
||||||
|
return result
|
||||||
|
|
||||||
|
def hasAttr(self, node, name, nsuri=None):
|
||||||
|
"""Return true if element has attribute with the given name and
|
||||||
|
optional nsuri. If nsuri is not specified, returns true if an
|
||||||
|
attribute exists with the given name with any namespace."""
|
||||||
|
if nsuri is None:
|
||||||
|
if node.hasAttribute(name):
|
||||||
|
return True
|
||||||
|
return False
|
||||||
|
return node.hasAttributeNS(nsuri, name)
|
||||||
|
|
||||||
|
def getAttr(self, node, name, nsuri=None, default=join):
|
||||||
|
"""Return the value of the attribute named 'name' with the
|
||||||
|
optional nsuri, or the default if one is specified. If
|
||||||
|
nsuri is not specified, an attribute that matches the
|
||||||
|
given name will be returned regardless of namespace."""
|
||||||
|
if nsuri is None:
|
||||||
|
result = node._attrs.get(name, None)
|
||||||
|
if result is None:
|
||||||
|
for item in node._attrsNS.keys():
|
||||||
|
if item[1] == name:
|
||||||
|
result = node._attrsNS[item]
|
||||||
|
break
|
||||||
|
else:
|
||||||
|
result = node._attrsNS.get((nsuri, name), None)
|
||||||
|
if result is not None:
|
||||||
|
return result.value
|
||||||
|
if default is not join:
|
||||||
|
return default
|
||||||
|
return ''
|
||||||
|
|
||||||
|
def getAttrs(self, node):
|
||||||
|
"""Return a Collection of all attributes
|
||||||
|
"""
|
||||||
|
attrs = {}
|
||||||
|
for k,v in node._attrs.items():
|
||||||
|
attrs[k] = v.value
|
||||||
|
return attrs
|
||||||
|
|
||||||
|
def getElementText(self, node, preserve_ws=None):
|
||||||
|
"""Return the text value of an xml element node. Leading and trailing
|
||||||
|
whitespace is stripped from the value unless the preserve_ws flag
|
||||||
|
is passed with a true value."""
|
||||||
|
result = []
|
||||||
|
for child in node.childNodes:
|
||||||
|
nodetype = child.nodeType
|
||||||
|
if nodetype == child.TEXT_NODE or \
|
||||||
|
nodetype == child.CDATA_SECTION_NODE:
|
||||||
|
result.append(child.nodeValue)
|
||||||
|
value = join(result, '')
|
||||||
|
if preserve_ws is None:
|
||||||
|
value = strip(value)
|
||||||
|
return value
|
||||||
|
|
||||||
|
def findNamespaceURI(self, prefix, node):
|
||||||
|
"""Find a namespace uri given a prefix and a context node."""
|
||||||
|
attrkey = (self.NS_XMLNS, prefix)
|
||||||
|
DOCUMENT_NODE = node.DOCUMENT_NODE
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
while 1:
|
||||||
|
if node.nodeType != ELEMENT_NODE:
|
||||||
|
node = node.parentNode
|
||||||
|
continue
|
||||||
|
result = node._attrsNS.get(attrkey, None)
|
||||||
|
if result is not None:
|
||||||
|
return result.value
|
||||||
|
if hasattr(node, '__imported__'):
|
||||||
|
raise DOMException('Value for prefix %s not found.' % prefix)
|
||||||
|
node = node.parentNode
|
||||||
|
if node.nodeType == DOCUMENT_NODE:
|
||||||
|
raise DOMException('Value for prefix %s not found.' % prefix)
|
||||||
|
|
||||||
|
def findDefaultNS(self, node):
|
||||||
|
"""Return the current default namespace uri for the given node."""
|
||||||
|
attrkey = (self.NS_XMLNS, 'xmlns')
|
||||||
|
DOCUMENT_NODE = node.DOCUMENT_NODE
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
while 1:
|
||||||
|
if node.nodeType != ELEMENT_NODE:
|
||||||
|
node = node.parentNode
|
||||||
|
continue
|
||||||
|
result = node._attrsNS.get(attrkey, None)
|
||||||
|
if result is not None:
|
||||||
|
return result.value
|
||||||
|
if hasattr(node, '__imported__'):
|
||||||
|
raise DOMException('Cannot determine default namespace.')
|
||||||
|
node = node.parentNode
|
||||||
|
if node.nodeType == DOCUMENT_NODE:
|
||||||
|
raise DOMException('Cannot determine default namespace.')
|
||||||
|
|
||||||
|
def findTargetNS(self, node):
|
||||||
|
"""Return the defined target namespace uri for the given node."""
|
||||||
|
attrget = self.getAttr
|
||||||
|
attrkey = (self.NS_XMLNS, 'xmlns')
|
||||||
|
DOCUMENT_NODE = node.DOCUMENT_NODE
|
||||||
|
ELEMENT_NODE = node.ELEMENT_NODE
|
||||||
|
while 1:
|
||||||
|
if node.nodeType != ELEMENT_NODE:
|
||||||
|
node = node.parentNode
|
||||||
|
continue
|
||||||
|
result = attrget(node, 'targetNamespace', default=None)
|
||||||
|
if result is not None:
|
||||||
|
return result
|
||||||
|
node = node.parentNode
|
||||||
|
if node.nodeType == DOCUMENT_NODE:
|
||||||
|
raise DOMException('Cannot determine target namespace.')
|
||||||
|
|
||||||
|
def getTypeRef(self, element):
|
||||||
|
"""Return (namespaceURI, name) for a type attribue of the given
|
||||||
|
element, or None if the element does not have a type attribute."""
|
||||||
|
typeattr = self.getAttr(element, 'type', default=None)
|
||||||
|
if typeattr is None:
|
||||||
|
return None
|
||||||
|
parts = typeattr.split(':', 1)
|
||||||
|
if len(parts) == 2:
|
||||||
|
nsuri = self.findNamespaceURI(parts[0], element)
|
||||||
|
else:
|
||||||
|
nsuri = self.findDefaultNS(element)
|
||||||
|
return (nsuri, parts[1])
|
||||||
|
|
||||||
|
def importNode(self, document, node, deep=0):
|
||||||
|
"""Implements (well enough for our purposes) DOM node import."""
|
||||||
|
nodetype = node.nodeType
|
||||||
|
if nodetype in (node.DOCUMENT_NODE, node.DOCUMENT_TYPE_NODE):
|
||||||
|
raise DOMException('Illegal node type for importNode')
|
||||||
|
if nodetype == node.ENTITY_REFERENCE_NODE:
|
||||||
|
deep = 0
|
||||||
|
clone = node.cloneNode(deep)
|
||||||
|
self._setOwnerDoc(document, clone)
|
||||||
|
clone.__imported__ = 1
|
||||||
|
return clone
|
||||||
|
|
||||||
|
def _setOwnerDoc(self, document, node):
|
||||||
|
node.ownerDocument = document
|
||||||
|
for child in node.childNodes:
|
||||||
|
self._setOwnerDoc(document, child)
|
||||||
|
|
||||||
|
def nsUriMatch(self, value, wanted, strict=0, tt=type(())):
|
||||||
|
"""Return a true value if two namespace uri values match."""
|
||||||
|
if value == wanted or (type(wanted) is tt) and value in wanted:
|
||||||
|
return 1
|
||||||
|
if not strict:
|
||||||
|
wanted = type(wanted) is tt and wanted or (wanted,)
|
||||||
|
value = value[-1:] != '/' and value or value[:-1]
|
||||||
|
for item in wanted:
|
||||||
|
if item == value or item[:-1] == value:
|
||||||
|
return 1
|
||||||
|
return 0
|
||||||
|
|
||||||
|
def createDocument(self, nsuri, qname, doctype=None):
|
||||||
|
"""Create a new writable DOM document object."""
|
||||||
|
impl = xml.dom.minidom.getDOMImplementation()
|
||||||
|
return impl.createDocument(nsuri, qname, doctype)
|
||||||
|
|
||||||
|
def loadDocument(self, data):
|
||||||
|
"""Load an xml file from a file-like object and return a DOM
|
||||||
|
document instance."""
|
||||||
|
return xml.dom.minidom.parse(data)
|
||||||
|
|
||||||
|
def loadFromURL(self, url):
|
||||||
|
"""Load an xml file from a URL and return a DOM document."""
|
||||||
|
file = urlopen(url)
|
||||||
|
try: result = self.loadDocument(file)
|
||||||
|
finally: file.close()
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
class DOMException(Exception):
|
||||||
|
pass
|
||||||
|
|
||||||
|
DOM = DOM()
|
||||||
|
|
||||||
|
|
||||||
|
class Collection(UserDict):
|
||||||
|
"""Helper class for maintaining ordered named collections."""
|
||||||
|
default = lambda self,k: k.name
|
||||||
|
def __init__(self, parent, key=None):
|
||||||
|
UserDict.__init__(self)
|
||||||
|
self.parent = weakref.ref(parent)
|
||||||
|
self.list = []
|
||||||
|
self._func = key or self.default
|
||||||
|
|
||||||
|
def __getitem__(self, key):
|
||||||
|
if type(key) is type(1):
|
||||||
|
return self.list[key]
|
||||||
|
return self.data[key]
|
||||||
|
|
||||||
|
def __setitem__(self, key, item):
|
||||||
|
item.parent = weakref.ref(self)
|
||||||
|
self.list.append(item)
|
||||||
|
self.data[key] = item
|
||||||
|
|
||||||
|
def keys(self):
|
||||||
|
return map(lambda i: self._func(i), self.list)
|
||||||
|
|
||||||
|
def items(self):
|
||||||
|
return map(lambda i: (self._func(i), i), self.list)
|
||||||
|
|
||||||
|
def values(self):
|
||||||
|
return self.list
|
||||||
|
|
||||||
|
|
||||||
|
class CollectionNS(UserDict):
|
||||||
|
"""Helper class for maintaining ordered named collections."""
|
||||||
|
default = lambda self,k: k.name
|
||||||
|
def __init__(self, parent, key=None):
|
||||||
|
UserDict.__init__(self)
|
||||||
|
self.parent = weakref.ref(parent)
|
||||||
|
self.targetNamespace = None
|
||||||
|
self.list = []
|
||||||
|
self._func = key or self.default
|
||||||
|
|
||||||
|
def __getitem__(self, key):
|
||||||
|
self.targetNamespace = self.parent().targetNamespace
|
||||||
|
if type(key) is types.IntType:
|
||||||
|
return self.list[key]
|
||||||
|
elif self.__isSequence(key):
|
||||||
|
nsuri,name = key
|
||||||
|
return self.data[nsuri][name]
|
||||||
|
return self.data[self.parent().targetNamespace][key]
|
||||||
|
|
||||||
|
def __setitem__(self, key, item):
|
||||||
|
item.parent = weakref.ref(self)
|
||||||
|
self.list.append(item)
|
||||||
|
targetNamespace = getattr(item, 'targetNamespace', self.parent().targetNamespace)
|
||||||
|
if not self.data.has_key(targetNamespace):
|
||||||
|
self.data[targetNamespace] = {}
|
||||||
|
self.data[targetNamespace][key] = item
|
||||||
|
|
||||||
|
def __isSequence(self, key):
|
||||||
|
return (type(key) in (types.TupleType,types.ListType) and len(key) == 2)
|
||||||
|
|
||||||
|
def keys(self):
|
||||||
|
keys = []
|
||||||
|
for tns in self.data.keys():
|
||||||
|
keys.append(map(lambda i: (tns,self._func(i)), self.data[tns].values()))
|
||||||
|
return keys
|
||||||
|
|
||||||
|
def items(self):
|
||||||
|
return map(lambda i: (self._func(i), i), self.list)
|
||||||
|
|
||||||
|
def values(self):
|
||||||
|
return self.list
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# This is a runtime guerilla patch for pulldom (used by minidom) so
|
||||||
|
# that xml namespace declaration attributes are not lost in parsing.
|
||||||
|
# We need them to do correct QName linking for XML Schema and WSDL.
|
||||||
|
# The patch has been submitted to SF for the next Python version.
|
||||||
|
|
||||||
|
from xml.dom.pulldom import PullDOM, START_ELEMENT
|
||||||
|
if 1:
|
||||||
|
def startPrefixMapping(self, prefix, uri):
|
||||||
|
if not hasattr(self, '_xmlns_attrs'):
|
||||||
|
self._xmlns_attrs = []
|
||||||
|
self._xmlns_attrs.append((prefix or 'xmlns', uri))
|
||||||
|
self._ns_contexts.append(self._current_context.copy())
|
||||||
|
self._current_context[uri] = prefix or ''
|
||||||
|
|
||||||
|
PullDOM.startPrefixMapping = startPrefixMapping
|
||||||
|
|
||||||
|
def startElementNS(self, name, tagName , attrs):
|
||||||
|
# Retrieve xml namespace declaration attributes.
|
||||||
|
xmlns_uri = 'http://www.w3.org/2000/xmlns/'
|
||||||
|
xmlns_attrs = getattr(self, '_xmlns_attrs', None)
|
||||||
|
if xmlns_attrs is not None:
|
||||||
|
for aname, value in xmlns_attrs:
|
||||||
|
attrs._attrs[(xmlns_uri, aname)] = value
|
||||||
|
self._xmlns_attrs = []
|
||||||
|
uri, localname = name
|
||||||
|
if uri:
|
||||||
|
# When using namespaces, the reader may or may not
|
||||||
|
# provide us with the original name. If not, create
|
||||||
|
# *a* valid tagName from the current context.
|
||||||
|
if tagName is None:
|
||||||
|
prefix = self._current_context[uri]
|
||||||
|
if prefix:
|
||||||
|
tagName = prefix + ":" + localname
|
||||||
|
else:
|
||||||
|
tagName = localname
|
||||||
|
if self.document:
|
||||||
|
node = self.document.createElementNS(uri, tagName)
|
||||||
|
else:
|
||||||
|
node = self.buildDocument(uri, tagName)
|
||||||
|
else:
|
||||||
|
# When the tagname is not prefixed, it just appears as
|
||||||
|
# localname
|
||||||
|
if self.document:
|
||||||
|
node = self.document.createElement(localname)
|
||||||
|
else:
|
||||||
|
node = self.buildDocument(None, localname)
|
||||||
|
|
||||||
|
for aname,value in attrs.items():
|
||||||
|
a_uri, a_localname = aname
|
||||||
|
if a_uri == xmlns_uri:
|
||||||
|
if a_localname == 'xmlns':
|
||||||
|
qname = a_localname
|
||||||
|
else:
|
||||||
|
qname = 'xmlns:' + a_localname
|
||||||
|
attr = self.document.createAttributeNS(a_uri, qname)
|
||||||
|
node.setAttributeNodeNS(attr)
|
||||||
|
elif a_uri:
|
||||||
|
prefix = self._current_context[a_uri]
|
||||||
|
if prefix:
|
||||||
|
qname = prefix + ":" + a_localname
|
||||||
|
else:
|
||||||
|
qname = a_localname
|
||||||
|
attr = self.document.createAttributeNS(a_uri, qname)
|
||||||
|
node.setAttributeNodeNS(attr)
|
||||||
|
else:
|
||||||
|
attr = self.document.createAttribute(a_localname)
|
||||||
|
node.setAttributeNode(attr)
|
||||||
|
attr.value = value
|
||||||
|
|
||||||
|
self.lastEvent[1] = [(START_ELEMENT, node), None]
|
||||||
|
self.lastEvent = self.lastEvent[1]
|
||||||
|
self.push(node)
|
||||||
|
|
||||||
|
PullDOM.startElementNS = startElementNS
|
||||||
|
|
||||||
|
#
|
||||||
|
# This is a runtime guerilla patch for minidom so
|
||||||
|
# that xmlns prefixed attributes dont raise AttributeErrors
|
||||||
|
# during cloning.
|
||||||
|
#
|
||||||
|
# Namespace declarations can appear in any start-tag, must look for xmlns
|
||||||
|
# prefixed attribute names during cloning.
|
||||||
|
#
|
||||||
|
# key (attr.namespaceURI, tag)
|
||||||
|
# ('http://www.w3.org/2000/xmlns/', u'xsd') <xml.dom.minidom.Attr instance at 0x82227c4>
|
||||||
|
# ('http://www.w3.org/2000/xmlns/', 'xmlns') <xml.dom.minidom.Attr instance at 0x8414b3c>
|
||||||
|
#
|
||||||
|
# xml.dom.minidom.Attr.nodeName = xmlns:xsd
|
||||||
|
# xml.dom.minidom.Attr.value = = http://www.w3.org/2001/XMLSchema
|
||||||
|
|
||||||
|
if 1:
|
||||||
|
def _clone_node(node, deep, newOwnerDocument):
|
||||||
|
"""
|
||||||
|
Clone a node and give it the new owner document.
|
||||||
|
Called by Node.cloneNode and Document.importNode
|
||||||
|
"""
|
||||||
|
if node.ownerDocument.isSameNode(newOwnerDocument):
|
||||||
|
operation = xml.dom.UserDataHandler.NODE_CLONED
|
||||||
|
else:
|
||||||
|
operation = xml.dom.UserDataHandler.NODE_IMPORTED
|
||||||
|
if node.nodeType == xml.dom.minidom.Node.ELEMENT_NODE:
|
||||||
|
clone = newOwnerDocument.createElementNS(node.namespaceURI,
|
||||||
|
node.nodeName)
|
||||||
|
for attr in node.attributes.values():
|
||||||
|
clone.setAttributeNS(attr.namespaceURI, attr.nodeName, attr.value)
|
||||||
|
|
||||||
|
prefix, tag = xml.dom.minidom._nssplit(attr.nodeName)
|
||||||
|
if prefix == 'xmlns':
|
||||||
|
a = clone.getAttributeNodeNS(attr.namespaceURI, tag)
|
||||||
|
elif prefix:
|
||||||
|
a = clone.getAttributeNodeNS(attr.namespaceURI, tag)
|
||||||
|
else:
|
||||||
|
a = clone.getAttributeNodeNS(attr.namespaceURI, attr.nodeName)
|
||||||
|
a.specified = attr.specified
|
||||||
|
|
||||||
|
if deep:
|
||||||
|
for child in node.childNodes:
|
||||||
|
c = xml.dom.minidom._clone_node(child, deep, newOwnerDocument)
|
||||||
|
clone.appendChild(c)
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.DOCUMENT_FRAGMENT_NODE:
|
||||||
|
clone = newOwnerDocument.createDocumentFragment()
|
||||||
|
if deep:
|
||||||
|
for child in node.childNodes:
|
||||||
|
c = xml.dom.minidom._clone_node(child, deep, newOwnerDocument)
|
||||||
|
clone.appendChild(c)
|
||||||
|
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.TEXT_NODE:
|
||||||
|
clone = newOwnerDocument.createTextNode(node.data)
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.CDATA_SECTION_NODE:
|
||||||
|
clone = newOwnerDocument.createCDATASection(node.data)
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE:
|
||||||
|
clone = newOwnerDocument.createProcessingInstruction(node.target,
|
||||||
|
node.data)
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.COMMENT_NODE:
|
||||||
|
clone = newOwnerDocument.createComment(node.data)
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.ATTRIBUTE_NODE:
|
||||||
|
clone = newOwnerDocument.createAttributeNS(node.namespaceURI,
|
||||||
|
node.nodeName)
|
||||||
|
clone.specified = True
|
||||||
|
clone.value = node.value
|
||||||
|
elif node.nodeType == xml.dom.minidom.Node.DOCUMENT_TYPE_NODE:
|
||||||
|
assert node.ownerDocument is not newOwnerDocument
|
||||||
|
operation = xml.dom.UserDataHandler.NODE_IMPORTED
|
||||||
|
clone = newOwnerDocument.implementation.createDocumentType(
|
||||||
|
node.name, node.publicId, node.systemId)
|
||||||
|
clone.ownerDocument = newOwnerDocument
|
||||||
|
if deep:
|
||||||
|
clone.entities._seq = []
|
||||||
|
clone.notations._seq = []
|
||||||
|
for n in node.notations._seq:
|
||||||
|
notation = xml.dom.minidom.Notation(n.nodeName, n.publicId, n.systemId)
|
||||||
|
notation.ownerDocument = newOwnerDocument
|
||||||
|
clone.notations._seq.append(notation)
|
||||||
|
if hasattr(n, '_call_user_data_handler'):
|
||||||
|
n._call_user_data_handler(operation, n, notation)
|
||||||
|
for e in node.entities._seq:
|
||||||
|
entity = xml.dom.minidom.Entity(e.nodeName, e.publicId, e.systemId,
|
||||||
|
e.notationName)
|
||||||
|
entity.actualEncoding = e.actualEncoding
|
||||||
|
entity.encoding = e.encoding
|
||||||
|
entity.version = e.version
|
||||||
|
entity.ownerDocument = newOwnerDocument
|
||||||
|
clone.entities._seq.append(entity)
|
||||||
|
if hasattr(e, '_call_user_data_handler'):
|
||||||
|
e._call_user_data_handler(operation, n, entity)
|
||||||
|
else:
|
||||||
|
# Note the cloning of Document and DocumentType nodes is
|
||||||
|
# implemenetation specific. minidom handles those cases
|
||||||
|
# directly in the cloneNode() methods.
|
||||||
|
raise xml.dom.NotSupportedErr("Cannot clone node %s" % repr(node))
|
||||||
|
|
||||||
|
# Check for _call_user_data_handler() since this could conceivably
|
||||||
|
# used with other DOM implementations (one of the FourThought
|
||||||
|
# DOMs, perhaps?).
|
||||||
|
if hasattr(node, '_call_user_data_handler'):
|
||||||
|
node._call_user_data_handler(operation, node, clone)
|
||||||
|
return clone
|
||||||
|
|
||||||
|
xml.dom.minidom._clone_node = _clone_node
|
||||||
1336
others/SOAPpy/wstools/WSDLTools.py
Executable file
1336
others/SOAPpy/wstools/WSDLTools.py
Executable file
File diff suppressed because it is too large
Load Diff
2976
others/SOAPpy/wstools/XMLSchema.py
Executable file
2976
others/SOAPpy/wstools/XMLSchema.py
Executable file
File diff suppressed because it is too large
Load Diff
88
others/SOAPpy/wstools/XMLname.py
Executable file
88
others/SOAPpy/wstools/XMLname.py
Executable file
@ -0,0 +1,88 @@
|
|||||||
|
"""Translate strings to and from SOAP 1.2 XML name encoding
|
||||||
|
|
||||||
|
Implements rules for mapping application defined name to XML names
|
||||||
|
specified by the w3 SOAP working group for SOAP version 1.2 in
|
||||||
|
Appendix A of "SOAP Version 1.2 Part 2: Adjuncts", W3C Working Draft
|
||||||
|
17, December 2001, <http://www.w3.org/TR/soap12-part2/#namemap>
|
||||||
|
|
||||||
|
Also see <http://www.w3.org/2000/xp/Group/xmlp-issues>.
|
||||||
|
|
||||||
|
Author: Gregory R. Warnes <gregory_r_warnes@groton.pfizer.com>
|
||||||
|
Date:: 2002-04-25
|
||||||
|
Version 0.9.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
ident = "$Id$"
|
||||||
|
|
||||||
|
from re import *
|
||||||
|
|
||||||
|
|
||||||
|
def _NCNameChar(x):
|
||||||
|
return x.isalpha() or x.isdigit() or x=="." or x=='-' or x=="_"
|
||||||
|
|
||||||
|
|
||||||
|
def _NCNameStartChar(x):
|
||||||
|
return x.isalpha() or x=="_"
|
||||||
|
|
||||||
|
|
||||||
|
def _toUnicodeHex(x):
|
||||||
|
hexval = hex(ord(x[0]))[2:]
|
||||||
|
hexlen = len(hexval)
|
||||||
|
# Make hexval have either 4 or 8 digits by prepending 0's
|
||||||
|
if (hexlen==1): hexval = "000" + hexval
|
||||||
|
elif (hexlen==2): hexval = "00" + hexval
|
||||||
|
elif (hexlen==3): hexval = "0" + hexval
|
||||||
|
elif (hexlen==4): hexval = "" + hexval
|
||||||
|
elif (hexlen==5): hexval = "000" + hexval
|
||||||
|
elif (hexlen==6): hexval = "00" + hexval
|
||||||
|
elif (hexlen==7): hexval = "0" + hexval
|
||||||
|
elif (hexlen==8): hexval = "" + hexval
|
||||||
|
else: raise Exception, "Illegal Value returned from hex(ord(x))"
|
||||||
|
|
||||||
|
return "_x"+ hexval + "_"
|
||||||
|
|
||||||
|
|
||||||
|
def _fromUnicodeHex(x):
|
||||||
|
return eval( r'u"\u'+x[2:-1]+'"' )
|
||||||
|
|
||||||
|
|
||||||
|
def toXMLname(string):
|
||||||
|
"""Convert string to a XML name."""
|
||||||
|
if string.find(':') != -1 :
|
||||||
|
(prefix, localname) = string.split(':',1)
|
||||||
|
else:
|
||||||
|
prefix = None
|
||||||
|
localname = string
|
||||||
|
|
||||||
|
T = unicode(localname)
|
||||||
|
|
||||||
|
N = len(localname)
|
||||||
|
X = [];
|
||||||
|
for i in range(N) :
|
||||||
|
if i< N-1 and T[i]==u'_' and T[i+1]==u'x':
|
||||||
|
X.append(u'_x005F_')
|
||||||
|
elif i==0 and N >= 3 and \
|
||||||
|
( T[0]==u'x' or T[0]==u'X' ) and \
|
||||||
|
( T[1]==u'm' or T[1]==u'M' ) and \
|
||||||
|
( T[2]==u'l' or T[2]==u'L' ):
|
||||||
|
X.append(u'_xFFFF_' + T[0])
|
||||||
|
elif (not _NCNameChar(T[i])) or (i==0 and not _NCNameStartChar(T[i])):
|
||||||
|
X.append(_toUnicodeHex(T[i]))
|
||||||
|
else:
|
||||||
|
X.append(T[i])
|
||||||
|
|
||||||
|
return u''.join(X)
|
||||||
|
|
||||||
|
|
||||||
|
def fromXMLname(string):
|
||||||
|
"""Convert XML name to unicode string."""
|
||||||
|
|
||||||
|
retval = sub(r'_xFFFF_','', string )
|
||||||
|
|
||||||
|
def fun( matchobj ):
|
||||||
|
return _fromUnicodeHex( matchobj.group(0) )
|
||||||
|
|
||||||
|
retval = sub(r'_x[0-9A-Za-z]+_', fun, retval )
|
||||||
|
|
||||||
|
return retval
|
||||||
35
others/SOAPpy/wstools/__init__.py
Normal file
35
others/SOAPpy/wstools/__init__.py
Normal file
@ -0,0 +1,35 @@
|
|||||||
|
"""WSDL parsing services package for Web Services for Python."""
|
||||||
|
|
||||||
|
ident = "$Id$"
|
||||||
|
|
||||||
|
import WSDLTools
|
||||||
|
import XMLname
|
||||||
|
from logging import getLogger as _getLogger
|
||||||
|
import logging.config as _config
|
||||||
|
|
||||||
|
LOGGING = 'logging.txt'
|
||||||
|
DEBUG = True
|
||||||
|
|
||||||
|
#
|
||||||
|
# If LOGGING configuration file is not found, turn off logging
|
||||||
|
# and use _noLogger class because logging module's performance
|
||||||
|
# is terrible.
|
||||||
|
#
|
||||||
|
|
||||||
|
try:
|
||||||
|
_config.fileConfig(LOGGING)
|
||||||
|
except:
|
||||||
|
DEBUG = False
|
||||||
|
|
||||||
|
|
||||||
|
class Base:
|
||||||
|
def __init__(self, module=__name__):
|
||||||
|
self.logger = _noLogger()
|
||||||
|
if DEBUG is True:
|
||||||
|
self.logger = _getLogger('%s-%s(%x)' %(module, self.__class__, id(self)))
|
||||||
|
|
||||||
|
class _noLogger:
|
||||||
|
def __init__(self, *args): pass
|
||||||
|
def warning(self, *args): pass
|
||||||
|
def debug(self, *args): pass
|
||||||
|
def error(self, *args): pass
|
||||||
0
others/__init__.py
Normal file
0
others/__init__.py
Normal file
364
others/amazon.py
Normal file
364
others/amazon.py
Normal file
@ -0,0 +1,364 @@
|
|||||||
|
"""Python wrapper
|
||||||
|
|
||||||
|
|
||||||
|
for Amazon web APIs
|
||||||
|
|
||||||
|
This module allows you to access Amazon's web APIs,
|
||||||
|
to do things like search Amazon and get the results programmatically.
|
||||||
|
Described here:
|
||||||
|
http://www.amazon.com/webservices
|
||||||
|
|
||||||
|
You need a Amazon-provided license key to use these services.
|
||||||
|
Follow the link above to get one. These functions will look in
|
||||||
|
several places (in this order) for the license key:
|
||||||
|
- the "license_key" argument of each function
|
||||||
|
- the module-level LICENSE_KEY variable (call setLicense once to set it)
|
||||||
|
- an environment variable called AMAZON_LICENSE_KEY
|
||||||
|
- a file called ".amazonkey" in the current directory
|
||||||
|
- a file called "amazonkey.txt" in the current directory
|
||||||
|
- a file called ".amazonkey" in your home directory
|
||||||
|
- a file called "amazonkey.txt" in your home directory
|
||||||
|
- a file called ".amazonkey" in the same directory as amazon.py
|
||||||
|
- a file called "amazonkey.txt" in the same directory as amazon.py
|
||||||
|
|
||||||
|
Sample usage:
|
||||||
|
>>> import amazon
|
||||||
|
>>> amazon.setLicense('...') # must get your own key!
|
||||||
|
>>> pythonBooks = amazon.searchByKeyword('Python')
|
||||||
|
>>> pythonBooks[0].ProductName
|
||||||
|
u'Learning Python (Help for Programmers)'
|
||||||
|
>>> pythonBooks[0].URL
|
||||||
|
...
|
||||||
|
>>> pythonBooks[0].OurPrice
|
||||||
|
...
|
||||||
|
|
||||||
|
Other available functions:
|
||||||
|
- browseBestSellers
|
||||||
|
- searchByASIN
|
||||||
|
- searchByUPC
|
||||||
|
- searchByAuthor
|
||||||
|
- searchByArtist
|
||||||
|
- searchByActor
|
||||||
|
- searchByDirector
|
||||||
|
- searchByManufacturer
|
||||||
|
- searchByListMania
|
||||||
|
- searchSimilar
|
||||||
|
- searchByWishlist
|
||||||
|
|
||||||
|
Other usage notes:
|
||||||
|
- Most functions can take product_line as well, see source for possible values
|
||||||
|
- All functions can take type="lite" to get less detail in results
|
||||||
|
- All functions can take page=N to get second, third, fourth page of results
|
||||||
|
- All functions can take license_key="XYZ", instead of setting it globally
|
||||||
|
- All functions can take http_proxy="http://x/y/z" which overrides your system setting
|
||||||
|
"""
|
||||||
|
|
||||||
|
__author__ = "Mark Pilgrim (f8dy@diveintomark.org)"
|
||||||
|
__version__ = "0.64.1"
|
||||||
|
__cvsversion__ = "$Revision$"[11:-2]
|
||||||
|
__date__ = "$Date$"[7:-2]
|
||||||
|
__copyright__ = "Copyright (c) 2002 Mark Pilgrim"
|
||||||
|
__license__ = "Python"
|
||||||
|
# Powersearch and return object type fix by Joseph Reagle <geek@goatee.net>
|
||||||
|
|
||||||
|
# Locale support by Michael Josephson <mike@josephson.org>
|
||||||
|
|
||||||
|
# Modification to _contentsOf to strip trailing whitespace when loading Amazon key
|
||||||
|
# from a file submitted by Patrick Phalen.
|
||||||
|
|
||||||
|
# Support for specifying locale and associates ID as search parameters and
|
||||||
|
# internationalisation fix for the SalesRank integer conversion by
|
||||||
|
# Christian Theune <ct@gocept.com>, gocept gmbh & co. kg
|
||||||
|
|
||||||
|
# Support for BlendedSearch contributed by Alex Choo
|
||||||
|
|
||||||
|
from xml.dom import minidom
|
||||||
|
import os, sys, getopt, cgi, urllib, string
|
||||||
|
try:
|
||||||
|
import timeoutsocket # http://www.timo-tasi.org/python/timeoutsocket.py
|
||||||
|
timeoutsocket.setDefaultSocketTimeout(10)
|
||||||
|
except ImportError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
LICENSE_KEY = None
|
||||||
|
ASSOCIATE = "webservices-20"
|
||||||
|
HTTP_PROXY = None
|
||||||
|
LOCALE = "us"
|
||||||
|
|
||||||
|
# don't touch the rest of these constants
|
||||||
|
class AmazonError(Exception): pass
|
||||||
|
class NoLicenseKey(Exception): pass
|
||||||
|
_amazonfile1 = ".amazonkey"
|
||||||
|
_amazonfile2 = "amazonkey.txt"
|
||||||
|
_licenseLocations = (
|
||||||
|
(lambda key: key, 'passed to the function in license_key variable'),
|
||||||
|
(lambda key: LICENSE_KEY, 'module-level LICENSE_KEY variable (call setLicense to set it)'),
|
||||||
|
(lambda key: os.environ.get('AMAZON_LICENSE_KEY', None), 'an environment variable called AMAZON_LICENSE_KEY'),
|
||||||
|
(lambda key: _contentsOf(os.getcwd(), _amazonfile1), '%s in the current directory' % _amazonfile1),
|
||||||
|
(lambda key: _contentsOf(os.getcwd(), _amazonfile2), '%s in the current directory' % _amazonfile2),
|
||||||
|
(lambda key: _contentsOf(os.environ.get('HOME', ''), _amazonfile1), '%s in your home directory' % _amazonfile1),
|
||||||
|
(lambda key: _contentsOf(os.environ.get('HOME', ''), _amazonfile2), '%s in your home directory' % _amazonfile2),
|
||||||
|
(lambda key: _contentsOf(_getScriptDir(), _amazonfile1), '%s in the amazon.py directory' % _amazonfile1),
|
||||||
|
(lambda key: _contentsOf(_getScriptDir(), _amazonfile2), '%s in the amazon.py directory' % _amazonfile2)
|
||||||
|
)
|
||||||
|
_supportedLocales = {
|
||||||
|
"us" : (None, "xml.amazon.com"),
|
||||||
|
"uk" : ("uk", "xml-eu.amazon.com"),
|
||||||
|
"de" : ("de", "xml-eu.amazon.com"),
|
||||||
|
"jp" : ("jp", "xml.amazon.co.jp")
|
||||||
|
}
|
||||||
|
|
||||||
|
## administrative functions
|
||||||
|
def version():
|
||||||
|
print """PyAmazon %(__version__)s
|
||||||
|
%(__copyright__)s
|
||||||
|
released %(__date__)s
|
||||||
|
""" % globals()
|
||||||
|
|
||||||
|
def setAssociate(associate):
|
||||||
|
global ASSOCIATE
|
||||||
|
ASSOCIATE=associate
|
||||||
|
|
||||||
|
def getAssociate(override=None):
|
||||||
|
return override or ASSOCIATE
|
||||||
|
|
||||||
|
## utility functions
|
||||||
|
|
||||||
|
def _checkLocaleSupported(locale):
|
||||||
|
if not _supportedLocales.has_key(locale):
|
||||||
|
raise AmazonError, ("Unsupported locale. Locale must be one of: %s" %
|
||||||
|
string.join(_supportedLocales, ", "))
|
||||||
|
|
||||||
|
def setLocale(locale):
|
||||||
|
"""set locale"""
|
||||||
|
global LOCALE
|
||||||
|
_checkLocaleSupported(locale)
|
||||||
|
LOCALE = locale
|
||||||
|
|
||||||
|
def getLocale(locale=None):
|
||||||
|
"""get locale"""
|
||||||
|
return locale or LOCALE
|
||||||
|
|
||||||
|
def setLicense(license_key):
|
||||||
|
"""set license key"""
|
||||||
|
global LICENSE_KEY
|
||||||
|
LICENSE_KEY = license_key
|
||||||
|
|
||||||
|
def getLicense(license_key = None):
|
||||||
|
"""get license key
|
||||||
|
|
||||||
|
license key can come from any number of locations;
|
||||||
|
see module docs for search order"""
|
||||||
|
for get, location in _licenseLocations:
|
||||||
|
rc = get(license_key)
|
||||||
|
if rc: return rc
|
||||||
|
raise NoLicenseKey, 'get a license key at http://www.amazon.com/webservices'
|
||||||
|
|
||||||
|
def setProxy(http_proxy):
|
||||||
|
"""set HTTP proxy"""
|
||||||
|
global HTTP_PROXY
|
||||||
|
HTTP_PROXY = http_proxy
|
||||||
|
|
||||||
|
def getProxy(http_proxy = None):
|
||||||
|
"""get HTTP proxy"""
|
||||||
|
return http_proxy or HTTP_PROXY
|
||||||
|
|
||||||
|
def getProxies(http_proxy = None):
|
||||||
|
http_proxy = getProxy(http_proxy)
|
||||||
|
if http_proxy:
|
||||||
|
proxies = {"http": http_proxy}
|
||||||
|
else:
|
||||||
|
proxies = None
|
||||||
|
return proxies
|
||||||
|
|
||||||
|
def _contentsOf(dirname, filename):
|
||||||
|
filename = os.path.join(dirname, filename)
|
||||||
|
if not os.path.exists(filename): return None
|
||||||
|
fsock = open(filename)
|
||||||
|
contents = fsock.read().strip()
|
||||||
|
fsock.close()
|
||||||
|
return contents
|
||||||
|
|
||||||
|
def _getScriptDir():
|
||||||
|
if __name__ == '__main__':
|
||||||
|
return os.path.abspath(os.path.dirname(sys.argv[0]))
|
||||||
|
else:
|
||||||
|
return os.path.abspath(os.path.dirname(sys.modules[__name__].__file__))
|
||||||
|
|
||||||
|
class Bag: pass
|
||||||
|
|
||||||
|
def unmarshal(element):
|
||||||
|
rc = Bag()
|
||||||
|
if isinstance(element, minidom.Element) and (element.tagName == 'Details'):
|
||||||
|
rc.URL = element.attributes["url"].value
|
||||||
|
childElements = [e for e in element.childNodes if isinstance(e, minidom.Element)]
|
||||||
|
if childElements:
|
||||||
|
for child in childElements:
|
||||||
|
key = child.tagName
|
||||||
|
if hasattr(rc, key):
|
||||||
|
if type(getattr(rc, key)) <> type([]):
|
||||||
|
setattr(rc, key, [getattr(rc, key)])
|
||||||
|
setattr(rc, key, getattr(rc, key) + [unmarshal(child)])
|
||||||
|
elif isinstance(child, minidom.Element) and (child.tagName == 'Details'):
|
||||||
|
# make the first Details element a key
|
||||||
|
setattr(rc,key,[unmarshal(child)])
|
||||||
|
#dbg: because otherwise 'hasattr' only tests
|
||||||
|
#dbg: on the second occurence: if there's a
|
||||||
|
#dbg: single return to a query, it's not a
|
||||||
|
#dbg: list. This module should always
|
||||||
|
#dbg: return a list of Details objects.
|
||||||
|
else:
|
||||||
|
setattr(rc, key, unmarshal(child))
|
||||||
|
else:
|
||||||
|
rc = "".join([e.data for e in element.childNodes if isinstance(e, minidom.Text)])
|
||||||
|
if element.tagName == 'SalesRank':
|
||||||
|
rc = rc.replace('.', '')
|
||||||
|
rc = rc.replace(',', '')
|
||||||
|
rc = int(rc)
|
||||||
|
return rc
|
||||||
|
|
||||||
|
def buildURL(search_type, keyword, product_line, type, page, license_key, locale, associate):
|
||||||
|
_checkLocaleSupported(locale)
|
||||||
|
url = "http://" + _supportedLocales[locale][1] + "/onca/xml3?f=xml"
|
||||||
|
url += "&t=%s" % associate
|
||||||
|
url += "&dev-t=%s" % license_key.strip()
|
||||||
|
url += "&type=%s" % type
|
||||||
|
if _supportedLocales[locale][0]:
|
||||||
|
url += "&locale=%s" % _supportedLocales[locale][0]
|
||||||
|
if page:
|
||||||
|
url += "&page=%s" % page
|
||||||
|
if product_line:
|
||||||
|
url += "&mode=%s" % product_line
|
||||||
|
url += "&%s=%s" % (search_type, urllib.quote(keyword))
|
||||||
|
return url
|
||||||
|
|
||||||
|
|
||||||
|
## main functions
|
||||||
|
|
||||||
|
|
||||||
|
def search(search_type, keyword, product_line, type = "heavy", page = None,
|
||||||
|
license_key=None, http_proxy = None, locale = None, associate = None):
|
||||||
|
"""search Amazon
|
||||||
|
|
||||||
|
You need a license key to call this function; see
|
||||||
|
http://www.amazon.com/webservices
|
||||||
|
to get one. Then you can either pass it to
|
||||||
|
this function every time, or set it globally; see the module docs for details.
|
||||||
|
|
||||||
|
Parameters:
|
||||||
|
keyword - keyword to search
|
||||||
|
search_type - in (KeywordSearch, BrowseNodeSearch, AsinSearch, UpcSearch, AuthorSearch, ArtistSearch, ActorSearch, DirectorSearch, ManufacturerSearch, ListManiaSearch, SimilaritySearch)
|
||||||
|
product_line - type of product to search for. restrictions based on search_type
|
||||||
|
UpcSearch - in (music, classical)
|
||||||
|
AuthorSearch - must be "books"
|
||||||
|
ArtistSearch - in (music, classical)
|
||||||
|
ActorSearch - in (dvd, vhs, video)
|
||||||
|
DirectorSearch - in (dvd, vhs, video)
|
||||||
|
ManufacturerSearch - in (electronics, kitchen, videogames, software, photo, pc-hardware)
|
||||||
|
http_proxy (optional) - address of HTTP proxy to use for sending and receiving SOAP messages
|
||||||
|
|
||||||
|
Returns: list of Bags, each Bag may contain the following attributes:
|
||||||
|
Asin - Amazon ID ("ASIN" number) of this item
|
||||||
|
Authors - list of authors
|
||||||
|
Availability - "available", etc.
|
||||||
|
BrowseList - list of related categories
|
||||||
|
Catalog - catalog type ("Book", etc)
|
||||||
|
CollectiblePrice - ?, format "$34.95"
|
||||||
|
ImageUrlLarge - URL of large image of this item
|
||||||
|
ImageUrlMedium - URL of medium image of this item
|
||||||
|
ImageUrlSmall - URL of small image of this item
|
||||||
|
Isbn - ISBN number
|
||||||
|
ListPrice - list price, format "$34.95"
|
||||||
|
Lists - list of ListMania lists that include this item
|
||||||
|
Manufacturer - manufacturer
|
||||||
|
Media - media ("Paperback", "Audio CD", etc)
|
||||||
|
NumMedia - number of different media types in which this item is available
|
||||||
|
OurPrice - Amazon price, format "$24.47"
|
||||||
|
ProductName - name of this item
|
||||||
|
ReleaseDate - release date, format "09 April, 1999"
|
||||||
|
Reviews - reviews (AvgCustomerRating, plus list of CustomerReview with Rating, Summary, Content)
|
||||||
|
SalesRank - sales rank (integer)
|
||||||
|
SimilarProducts - list of Product, which is ASIN number
|
||||||
|
ThirdPartyNewPrice - ?, format "$34.95"
|
||||||
|
URL - URL of this item
|
||||||
|
"""
|
||||||
|
license_key = getLicense(license_key)
|
||||||
|
locale = getLocale(locale)
|
||||||
|
associate = getAssociate(associate)
|
||||||
|
url = buildURL(search_type, keyword, product_line, type, page,
|
||||||
|
license_key, locale, associate)
|
||||||
|
proxies = getProxies(http_proxy)
|
||||||
|
u = urllib.FancyURLopener(proxies)
|
||||||
|
usock = u.open(url)
|
||||||
|
xmldoc = minidom.parse(usock)
|
||||||
|
|
||||||
|
# from xml.dom.ext import PrettyPrint
|
||||||
|
# PrettyPrint(xmldoc)
|
||||||
|
|
||||||
|
usock.close()
|
||||||
|
if search_type == "BlendedSearch":
|
||||||
|
data = unmarshal(xmldoc).BlendedSearch
|
||||||
|
else:
|
||||||
|
data = unmarshal(xmldoc).ProductInfo
|
||||||
|
|
||||||
|
if hasattr(data, 'ErrorMsg'):
|
||||||
|
raise AmazonError, data.ErrorMsg
|
||||||
|
else:
|
||||||
|
if search_type == "BlendedSearch":
|
||||||
|
# a list of ProductLine containing a list of ProductInfo
|
||||||
|
# containing a list of Details.
|
||||||
|
return data
|
||||||
|
else:
|
||||||
|
return data.Details
|
||||||
|
|
||||||
|
def searchByKeyword(keyword, product_line="books", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("KeywordSearch", keyword, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def browseBestSellers(browse_node, product_line="books", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("BrowseNodeSearch", browse_node, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByASIN(ASIN, type="heavy", license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("AsinSearch", ASIN, None, type, None, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByUPC(UPC, type="heavy", license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("UpcSearch", UPC, None, type, None, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByAuthor(author, type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("AuthorSearch", author, "books", type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByArtist(artist, product_line="music", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
if product_line not in ("music", "classical"):
|
||||||
|
raise AmazonError, "product_line must be in ('music', 'classical')"
|
||||||
|
return search("ArtistSearch", artist, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByActor(actor, product_line="dvd", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
if product_line not in ("dvd", "vhs", "video"):
|
||||||
|
raise AmazonError, "product_line must be in ('dvd', 'vhs', 'video')"
|
||||||
|
return search("ActorSearch", actor, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByDirector(director, product_line="dvd", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
if product_line not in ("dvd", "vhs", "video"):
|
||||||
|
raise AmazonError, "product_line must be in ('dvd', 'vhs', 'video')"
|
||||||
|
return search("DirectorSearch", director, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByManufacturer(manufacturer, product_line="pc-hardware", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
if product_line not in ("electronics", "kitchen", "videogames", "software", "photo", "pc-hardware"):
|
||||||
|
raise AmazonError, "product_line must be in ('electronics', 'kitchen', 'videogames', 'software', 'photo', 'pc-hardware')"
|
||||||
|
return search("ManufacturerSearch", manufacturer, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByListMania(listManiaID, type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("ListManiaSearch", listManiaID, None, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchSimilar(ASIN, type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("SimilaritySearch", ASIN, None, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByWishlist(wishlistID, type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("WishlistSearch", wishlistID, None, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
|
||||||
|
def searchByPower(keyword, product_line="books", type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("PowerSearch", keyword, product_line, type, page, license_key, http_proxy, locale, associate)
|
||||||
|
# >>> RecentKing = amazon.searchByPower('author:Stephen King and pubdate:2003')
|
||||||
|
# >>> SnowCrash = amazon.searchByPower('title:Snow Crash')
|
||||||
|
|
||||||
|
def searchByBlended(keyword, type="heavy", page=1, license_key=None, http_proxy=None, locale=None, associate=None):
|
||||||
|
return search("BlendedSearch", keyword, None, type, page, license_key, http_proxy, locale, associate)
|
||||||
294
others/asynchat.py
Normal file
294
others/asynchat.py
Normal file
@ -0,0 +1,294 @@
|
|||||||
|
# -*- Mode: Python; tab-width: 4 -*-
|
||||||
|
# Id: asynchat.py,v 2.26 2000/09/07 22:29:26 rushing Exp
|
||||||
|
# Author: Sam Rushing <rushing@nightmare.com>
|
||||||
|
|
||||||
|
# ======================================================================
|
||||||
|
# Copyright 1996 by Sam Rushing
|
||||||
|
#
|
||||||
|
# All Rights Reserved
|
||||||
|
#
|
||||||
|
# Permission to use, copy, modify, and distribute this software and
|
||||||
|
# its documentation for any purpose and without fee is hereby
|
||||||
|
# granted, provided that the above copyright notice appear in all
|
||||||
|
# copies and that both that copyright notice and this permission
|
||||||
|
# notice appear in supporting documentation, and that the name of Sam
|
||||||
|
# Rushing not be used in advertising or publicity pertaining to
|
||||||
|
# distribution of the software without specific, written prior
|
||||||
|
# permission.
|
||||||
|
#
|
||||||
|
# SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
||||||
|
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
|
||||||
|
# NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
|
||||||
|
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
|
||||||
|
# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||||
|
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
|
||||||
|
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
|
# ======================================================================
|
||||||
|
|
||||||
|
r"""A class supporting chat-style (command/response) protocols.
|
||||||
|
|
||||||
|
This class adds support for 'chat' style protocols - where one side
|
||||||
|
sends a 'command', and the other sends a response (examples would be
|
||||||
|
the common internet protocols - smtp, nntp, ftp, etc..).
|
||||||
|
|
||||||
|
The handle_read() method looks at the input stream for the current
|
||||||
|
'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
|
||||||
|
for multi-line output), calling self.found_terminator() on its
|
||||||
|
receipt.
|
||||||
|
|
||||||
|
for example:
|
||||||
|
Say you build an async nntp client using this class. At the start
|
||||||
|
of the connection, you'll have self.terminator set to '\r\n', in
|
||||||
|
order to process the single-line greeting. Just before issuing a
|
||||||
|
'LIST' command you'll set it to '\r\n.\r\n'. The output of the LIST
|
||||||
|
command will be accumulated (using your own 'collect_incoming_data'
|
||||||
|
method) up to the terminator, and then control will be returned to
|
||||||
|
you - by calling your self.found_terminator() method.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import socket
|
||||||
|
import asyncore
|
||||||
|
|
||||||
|
class async_chat (asyncore.dispatcher):
|
||||||
|
"""This is an abstract class. You must derive from this class, and add
|
||||||
|
the two methods collect_incoming_data() and found_terminator()"""
|
||||||
|
|
||||||
|
# these are overridable defaults
|
||||||
|
|
||||||
|
ac_in_buffer_size = 4096
|
||||||
|
ac_out_buffer_size = 4096
|
||||||
|
|
||||||
|
def __init__ (self, conn=None):
|
||||||
|
self.ac_in_buffer = ''
|
||||||
|
self.ac_out_buffer = ''
|
||||||
|
self.producer_fifo = fifo()
|
||||||
|
asyncore.dispatcher.__init__ (self, conn)
|
||||||
|
|
||||||
|
def set_terminator (self, term):
|
||||||
|
"Set the input delimiter. Can be a fixed string of any length, an integer, or None"
|
||||||
|
self.terminator = term
|
||||||
|
|
||||||
|
def get_terminator (self):
|
||||||
|
return self.terminator
|
||||||
|
|
||||||
|
# grab some more data from the socket,
|
||||||
|
# throw it to the collector method,
|
||||||
|
# check for the terminator,
|
||||||
|
# if found, transition to the next state.
|
||||||
|
|
||||||
|
def handle_read (self):
|
||||||
|
|
||||||
|
try:
|
||||||
|
data = self.recv (self.ac_in_buffer_size)
|
||||||
|
except socket.error, _:
|
||||||
|
self.handle_error()
|
||||||
|
return
|
||||||
|
|
||||||
|
self.ac_in_buffer = self.ac_in_buffer + data
|
||||||
|
|
||||||
|
# Continue to search for self.terminator in self.ac_in_buffer,
|
||||||
|
# while calling self.collect_incoming_data. The while loop
|
||||||
|
# is necessary because we might read several data+terminator
|
||||||
|
# combos with a single recv(1024).
|
||||||
|
|
||||||
|
while self.ac_in_buffer:
|
||||||
|
lb = len(self.ac_in_buffer)
|
||||||
|
terminator = self.get_terminator()
|
||||||
|
if terminator is None:
|
||||||
|
# no terminator, collect it all
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer)
|
||||||
|
self.ac_in_buffer = ''
|
||||||
|
elif type(terminator) == type(0):
|
||||||
|
# numeric terminator
|
||||||
|
n = terminator
|
||||||
|
if lb < n:
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer)
|
||||||
|
self.ac_in_buffer = ''
|
||||||
|
self.terminator = self.terminator - lb
|
||||||
|
else:
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer[:n])
|
||||||
|
self.ac_in_buffer = self.ac_in_buffer[n:]
|
||||||
|
self.terminator = 0
|
||||||
|
self.found_terminator()
|
||||||
|
else:
|
||||||
|
# 3 cases:
|
||||||
|
# 1) end of buffer matches terminator exactly:
|
||||||
|
# collect data, transition
|
||||||
|
# 2) end of buffer matches some prefix:
|
||||||
|
# collect data to the prefix
|
||||||
|
# 3) end of buffer does not match any prefix:
|
||||||
|
# collect data
|
||||||
|
terminator_len = len(terminator)
|
||||||
|
index = self.ac_in_buffer.find(terminator)
|
||||||
|
if index != -1:
|
||||||
|
# we found the terminator
|
||||||
|
if index > 0:
|
||||||
|
# don't bother reporting the empty string (source of subtle bugs)
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer[:index])
|
||||||
|
self.ac_in_buffer = self.ac_in_buffer[index+terminator_len:]
|
||||||
|
# This does the Right Thing if the terminator is changed here.
|
||||||
|
self.found_terminator()
|
||||||
|
else:
|
||||||
|
# check for a prefix of the terminator
|
||||||
|
index = find_prefix_at_end (self.ac_in_buffer, terminator)
|
||||||
|
if index:
|
||||||
|
if index != lb:
|
||||||
|
# we found a prefix, collect up to the prefix
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer[:-index])
|
||||||
|
self.ac_in_buffer = self.ac_in_buffer[-index:]
|
||||||
|
break
|
||||||
|
else:
|
||||||
|
# no prefix, collect it all
|
||||||
|
self.collect_incoming_data (self.ac_in_buffer)
|
||||||
|
self.ac_in_buffer = ''
|
||||||
|
|
||||||
|
def handle_write (self):
|
||||||
|
self.initiate_send ()
|
||||||
|
|
||||||
|
def handle_close (self):
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def push (self, data):
|
||||||
|
self.producer_fifo.push (simple_producer (data))
|
||||||
|
self.initiate_send()
|
||||||
|
|
||||||
|
def push_with_producer (self, producer):
|
||||||
|
self.producer_fifo.push (producer)
|
||||||
|
self.initiate_send()
|
||||||
|
|
||||||
|
def readable (self):
|
||||||
|
"predicate for inclusion in the readable for select()"
|
||||||
|
return (len(self.ac_in_buffer) <= self.ac_in_buffer_size)
|
||||||
|
|
||||||
|
def writable (self):
|
||||||
|
"predicate for inclusion in the writable for select()"
|
||||||
|
# return len(self.ac_out_buffer) or len(self.producer_fifo) or (not self.connected)
|
||||||
|
# this is about twice as fast, though not as clear.
|
||||||
|
return not (
|
||||||
|
(self.ac_out_buffer == '') and
|
||||||
|
self.producer_fifo.is_empty() and
|
||||||
|
self.connected
|
||||||
|
)
|
||||||
|
|
||||||
|
def close_when_done (self):
|
||||||
|
"automatically close this channel once the outgoing queue is empty"
|
||||||
|
self.producer_fifo.push (None)
|
||||||
|
|
||||||
|
# refill the outgoing buffer by calling the more() method
|
||||||
|
# of the first producer in the queue
|
||||||
|
def refill_buffer (self):
|
||||||
|
_string_type = type('')
|
||||||
|
while 1:
|
||||||
|
if len(self.producer_fifo):
|
||||||
|
p = self.producer_fifo.first()
|
||||||
|
# a 'None' in the producer fifo is a sentinel,
|
||||||
|
# telling us to close the channel.
|
||||||
|
if p is None:
|
||||||
|
if not self.ac_out_buffer:
|
||||||
|
self.producer_fifo.pop()
|
||||||
|
self.close()
|
||||||
|
return
|
||||||
|
elif type(p) is _string_type:
|
||||||
|
self.producer_fifo.pop()
|
||||||
|
self.ac_out_buffer = self.ac_out_buffer + p
|
||||||
|
return
|
||||||
|
data = p.more()
|
||||||
|
if data:
|
||||||
|
self.ac_out_buffer = self.ac_out_buffer + data
|
||||||
|
return
|
||||||
|
else:
|
||||||
|
self.producer_fifo.pop()
|
||||||
|
else:
|
||||||
|
return
|
||||||
|
|
||||||
|
def initiate_send (self):
|
||||||
|
obs = self.ac_out_buffer_size
|
||||||
|
# try to refill the buffer
|
||||||
|
if (len (self.ac_out_buffer) < obs):
|
||||||
|
self.refill_buffer()
|
||||||
|
|
||||||
|
if self.ac_out_buffer and self.connected:
|
||||||
|
# try to send the buffer
|
||||||
|
try:
|
||||||
|
num_sent = self.send (self.ac_out_buffer[:obs])
|
||||||
|
if num_sent:
|
||||||
|
self.ac_out_buffer = self.ac_out_buffer[num_sent:]
|
||||||
|
|
||||||
|
except socket.error, _:
|
||||||
|
self.handle_error()
|
||||||
|
return
|
||||||
|
|
||||||
|
def discard_buffers (self):
|
||||||
|
# Emergencies only!
|
||||||
|
self.ac_in_buffer = ''
|
||||||
|
self.ac_out_buffer = ''
|
||||||
|
while self.producer_fifo:
|
||||||
|
self.producer_fifo.pop()
|
||||||
|
|
||||||
|
|
||||||
|
class simple_producer:
|
||||||
|
|
||||||
|
def __init__ (self, data, buffer_size=512):
|
||||||
|
self.data = data
|
||||||
|
self.buffer_size = buffer_size
|
||||||
|
|
||||||
|
def more (self):
|
||||||
|
if len (self.data) > self.buffer_size:
|
||||||
|
result = self.data[:self.buffer_size]
|
||||||
|
self.data = self.data[self.buffer_size:]
|
||||||
|
return result
|
||||||
|
else:
|
||||||
|
result = self.data
|
||||||
|
self.data = ''
|
||||||
|
return result
|
||||||
|
|
||||||
|
class fifo:
|
||||||
|
def __init__ (self, list=None):
|
||||||
|
if not list:
|
||||||
|
self.list = []
|
||||||
|
else:
|
||||||
|
self.list = list
|
||||||
|
|
||||||
|
def __len__ (self):
|
||||||
|
return len(self.list)
|
||||||
|
|
||||||
|
def is_empty (self):
|
||||||
|
return self.list == []
|
||||||
|
|
||||||
|
def first (self):
|
||||||
|
return self.list[0]
|
||||||
|
|
||||||
|
def push (self, data):
|
||||||
|
self.list.append (data)
|
||||||
|
|
||||||
|
def pop (self):
|
||||||
|
if self.list:
|
||||||
|
result = self.list[0]
|
||||||
|
del self.list[0]
|
||||||
|
return (1, result)
|
||||||
|
else:
|
||||||
|
return (0, None)
|
||||||
|
|
||||||
|
# Given 'haystack', see if any prefix of 'needle' is at its end. This
|
||||||
|
# assumes an exact match has already been checked. Return the number of
|
||||||
|
# characters matched.
|
||||||
|
# for example:
|
||||||
|
# f_p_a_e ("qwerty\r", "\r\n") => 1
|
||||||
|
# f_p_a_e ("qwerty\r\n", "\r\n") => 2
|
||||||
|
# f_p_a_e ("qwertydkjf", "\r\n") => 0
|
||||||
|
|
||||||
|
# this could maybe be made faster with a computed regex?
|
||||||
|
# [answer: no; circa Python-2.0, Jan 2001]
|
||||||
|
# python: 18307/s
|
||||||
|
# re: 12820/s
|
||||||
|
# regex: 14035/s
|
||||||
|
|
||||||
|
def find_prefix_at_end (haystack, needle):
|
||||||
|
nl = len(needle)
|
||||||
|
result = 0
|
||||||
|
for i in range (1,nl):
|
||||||
|
if haystack[-(nl-i):] == needle[:(nl-i)]:
|
||||||
|
result = nl-i
|
||||||
|
break
|
||||||
|
return result
|
||||||
|
# vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78:
|
||||||
494
others/asyncore.py
Normal file
494
others/asyncore.py
Normal file
@ -0,0 +1,494 @@
|
|||||||
|
# -*- Mode: Python -*-
|
||||||
|
# Id: asyncore.py,v 2.51 2000/09/07 22:29:26 rushing Exp
|
||||||
|
# Author: Sam Rushing <rushing@nightmare.com>
|
||||||
|
|
||||||
|
# ======================================================================
|
||||||
|
# Copyright 1996 by Sam Rushing
|
||||||
|
#
|
||||||
|
# All Rights Reserved
|
||||||
|
#
|
||||||
|
# Permission to use, copy, modify, and distribute this software and
|
||||||
|
# its documentation for any purpose and without fee is hereby
|
||||||
|
# granted, provided that the above copyright notice appear in all
|
||||||
|
# copies and that both that copyright notice and this permission
|
||||||
|
# notice appear in supporting documentation, and that the name of Sam
|
||||||
|
# Rushing not be used in advertising or publicity pertaining to
|
||||||
|
# distribution of the software without specific, written prior
|
||||||
|
# permission.
|
||||||
|
#
|
||||||
|
# SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
||||||
|
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
|
||||||
|
# NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
|
||||||
|
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
|
||||||
|
# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||||
|
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
|
||||||
|
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
|
# ======================================================================
|
||||||
|
|
||||||
|
"""Basic infrastructure for asynchronous socket service clients and servers.
|
||||||
|
|
||||||
|
There are only two ways to have a program on a single processor do "more
|
||||||
|
than one thing at a time". Multi-threaded programming is the simplest and
|
||||||
|
most popular way to do it, but there is another very different technique,
|
||||||
|
that lets you have nearly all the advantages of multi-threading, without
|
||||||
|
actually using multiple threads. it's really only practical if your program
|
||||||
|
is largely I/O bound. If your program is CPU bound, then pre-emptive
|
||||||
|
scheduled threads are probably what you really need. Network servers are
|
||||||
|
rarely CPU-bound, however.
|
||||||
|
|
||||||
|
If your operating system supports the select() system call in its I/O
|
||||||
|
library (and nearly all do), then you can use it to juggle multiple
|
||||||
|
communication channels at once; doing other work while your I/O is taking
|
||||||
|
place in the "background." Although this strategy can seem strange and
|
||||||
|
complex, especially at first, it is in many ways easier to understand and
|
||||||
|
control than multi-threaded programming. The module documented here solves
|
||||||
|
many of the difficult problems for you, making the task of building
|
||||||
|
sophisticated high-performance network servers and clients a snap.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import exceptions
|
||||||
|
import select
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
import time
|
||||||
|
|
||||||
|
import os
|
||||||
|
from errno import EALREADY, EINPROGRESS, EWOULDBLOCK, ECONNRESET, \
|
||||||
|
ENOTCONN, ESHUTDOWN, EINTR, EISCONN
|
||||||
|
|
||||||
|
try:
|
||||||
|
socket_map
|
||||||
|
except NameError:
|
||||||
|
socket_map = {}
|
||||||
|
|
||||||
|
class ExitNow(exceptions.Exception):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def read(obj):
|
||||||
|
try:
|
||||||
|
obj.handle_read_event()
|
||||||
|
except ExitNow:
|
||||||
|
raise
|
||||||
|
except:
|
||||||
|
obj.handle_error()
|
||||||
|
|
||||||
|
def write(obj):
|
||||||
|
try:
|
||||||
|
obj.handle_write_event()
|
||||||
|
except ExitNow:
|
||||||
|
raise
|
||||||
|
except:
|
||||||
|
obj.handle_error()
|
||||||
|
|
||||||
|
def readwrite(obj, flags):
|
||||||
|
try:
|
||||||
|
if flags & select.POLLIN:
|
||||||
|
obj.handle_read_event()
|
||||||
|
if flags & select.POLLOUT:
|
||||||
|
obj.handle_write_event()
|
||||||
|
except ExitNow:
|
||||||
|
raise
|
||||||
|
except:
|
||||||
|
obj.handle_error()
|
||||||
|
|
||||||
|
def poll(timeout=0.0, map=None):
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
if map:
|
||||||
|
r = []; w = []; e = []
|
||||||
|
for fd, obj in map.items():
|
||||||
|
if obj.readable():
|
||||||
|
r.append(fd)
|
||||||
|
if obj.writable():
|
||||||
|
w.append(fd)
|
||||||
|
if [] == r == w == e:
|
||||||
|
time.sleep(timeout)
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
r, w, e = select.select(r, w, e, timeout)
|
||||||
|
except select.error, err:
|
||||||
|
if err[0] != EINTR:
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
return
|
||||||
|
|
||||||
|
for fd in r:
|
||||||
|
obj = map.get(fd)
|
||||||
|
if obj is None:
|
||||||
|
continue
|
||||||
|
read(obj)
|
||||||
|
|
||||||
|
for fd in w:
|
||||||
|
obj = map.get(fd)
|
||||||
|
if obj is None:
|
||||||
|
continue
|
||||||
|
write(obj)
|
||||||
|
|
||||||
|
def poll2(timeout=0.0, map=None):
|
||||||
|
import poll
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
if timeout is not None:
|
||||||
|
# timeout is in milliseconds
|
||||||
|
timeout = int(timeout*1000)
|
||||||
|
if map:
|
||||||
|
l = []
|
||||||
|
for fd, obj in map.items():
|
||||||
|
flags = 0
|
||||||
|
if obj.readable():
|
||||||
|
flags = poll.POLLIN
|
||||||
|
if obj.writable():
|
||||||
|
flags = flags | poll.POLLOUT
|
||||||
|
if flags:
|
||||||
|
l.append((fd, flags))
|
||||||
|
r = poll.poll(l, timeout)
|
||||||
|
for fd, flags in r:
|
||||||
|
obj = map.get(fd)
|
||||||
|
if obj is None:
|
||||||
|
continue
|
||||||
|
readwrite(obj, flags)
|
||||||
|
|
||||||
|
def poll3(timeout=0.0, map=None):
|
||||||
|
# Use the poll() support added to the select module in Python 2.0
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
if timeout is not None:
|
||||||
|
# timeout is in milliseconds
|
||||||
|
timeout = int(timeout*1000)
|
||||||
|
pollster = select.poll()
|
||||||
|
if map:
|
||||||
|
for fd, obj in map.items():
|
||||||
|
flags = 0
|
||||||
|
if obj.readable():
|
||||||
|
flags = select.POLLIN
|
||||||
|
if obj.writable():
|
||||||
|
flags = flags | select.POLLOUT
|
||||||
|
if flags:
|
||||||
|
pollster.register(fd, flags)
|
||||||
|
try:
|
||||||
|
r = pollster.poll(timeout)
|
||||||
|
except select.error, err:
|
||||||
|
if err[0] != EINTR:
|
||||||
|
raise
|
||||||
|
r = []
|
||||||
|
for fd, flags in r:
|
||||||
|
obj = map.get(fd)
|
||||||
|
if obj is None:
|
||||||
|
continue
|
||||||
|
readwrite(obj, flags)
|
||||||
|
|
||||||
|
def loop(timeout=30.0, use_poll=0, map=None):
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
|
||||||
|
if use_poll:
|
||||||
|
if hasattr(select, 'poll'):
|
||||||
|
poll_fun = poll3
|
||||||
|
else:
|
||||||
|
poll_fun = poll2
|
||||||
|
else:
|
||||||
|
poll_fun = poll
|
||||||
|
|
||||||
|
while map:
|
||||||
|
poll_fun(timeout, map)
|
||||||
|
|
||||||
|
class dispatcher:
|
||||||
|
|
||||||
|
debug = 0
|
||||||
|
connected = 0
|
||||||
|
accepting = 0
|
||||||
|
closing = 0
|
||||||
|
addr = None
|
||||||
|
|
||||||
|
def __init__(self, sock=None, map=None):
|
||||||
|
if sock:
|
||||||
|
self.set_socket(sock, map)
|
||||||
|
# I think it should inherit this anyway
|
||||||
|
self.socket.setblocking(0)
|
||||||
|
self.connected = 1
|
||||||
|
# XXX Does the constructor require that the socket passed
|
||||||
|
# be connected?
|
||||||
|
try:
|
||||||
|
self.addr = sock.getpeername()
|
||||||
|
except socket.error:
|
||||||
|
# The addr isn't crucial
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
self.socket = None
|
||||||
|
|
||||||
|
def __repr__(self):
|
||||||
|
status = [self.__class__.__module__+"."+self.__class__.__name__]
|
||||||
|
if self.accepting and self.addr:
|
||||||
|
status.append('listening')
|
||||||
|
elif self.connected:
|
||||||
|
status.append('connected')
|
||||||
|
if self.addr is not None:
|
||||||
|
try:
|
||||||
|
status.append('%s:%d' % self.addr)
|
||||||
|
except TypeError:
|
||||||
|
status.append(repr(self.addr))
|
||||||
|
return '<%s at %#x>' % (' '.join(status), id(self))
|
||||||
|
|
||||||
|
def add_channel(self, map=None):
|
||||||
|
#self.log_info('adding channel %s' % self)
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
map[self._fileno] = self
|
||||||
|
|
||||||
|
def del_channel(self, map=None):
|
||||||
|
fd = self._fileno
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
if map.has_key(fd):
|
||||||
|
#self.log_info('closing channel %d:%s' % (fd, self))
|
||||||
|
del map[fd]
|
||||||
|
|
||||||
|
def create_socket(self, family, type):
|
||||||
|
self.family_and_type = family, type
|
||||||
|
self.socket = socket.socket(family, type)
|
||||||
|
self.socket.setblocking(0)
|
||||||
|
self._fileno = self.socket.fileno()
|
||||||
|
self.add_channel()
|
||||||
|
|
||||||
|
def set_socket(self, sock, map=None):
|
||||||
|
self.socket = sock
|
||||||
|
## self.__dict__['socket'] = sock
|
||||||
|
self._fileno = sock.fileno()
|
||||||
|
self.add_channel(map)
|
||||||
|
|
||||||
|
def set_reuse_addr(self):
|
||||||
|
# try to re-use a server port if possible
|
||||||
|
try:
|
||||||
|
self.socket.setsockopt(
|
||||||
|
socket.SOL_SOCKET, socket.SO_REUSEADDR,
|
||||||
|
self.socket.getsockopt(socket.SOL_SOCKET,
|
||||||
|
socket.SO_REUSEADDR) | 1
|
||||||
|
)
|
||||||
|
except socket.error:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# ==================================================
|
||||||
|
# predicates for select()
|
||||||
|
# these are used as filters for the lists of sockets
|
||||||
|
# to pass to select().
|
||||||
|
# ==================================================
|
||||||
|
|
||||||
|
def readable(self):
|
||||||
|
return True
|
||||||
|
|
||||||
|
if os.name == 'mac':
|
||||||
|
# The macintosh will select a listening socket for
|
||||||
|
# write if you let it. What might this mean?
|
||||||
|
def writable(self):
|
||||||
|
return not self.accepting
|
||||||
|
else:
|
||||||
|
def writable(self):
|
||||||
|
return True
|
||||||
|
|
||||||
|
# ==================================================
|
||||||
|
# socket object methods.
|
||||||
|
# ==================================================
|
||||||
|
|
||||||
|
def listen(self, num):
|
||||||
|
self.accepting = 1
|
||||||
|
if os.name == 'nt' and num > 5:
|
||||||
|
num = 1
|
||||||
|
return self.socket.listen(num)
|
||||||
|
|
||||||
|
def bind(self, addr):
|
||||||
|
self.addr = addr
|
||||||
|
return self.socket.bind(addr)
|
||||||
|
|
||||||
|
def connect(self, address):
|
||||||
|
self.connected = 0
|
||||||
|
err = self.socket.connect_ex(address)
|
||||||
|
# XXX Should interpret Winsock return values
|
||||||
|
if err in (EINPROGRESS, EALREADY, EWOULDBLOCK):
|
||||||
|
return
|
||||||
|
if err in (0, EISCONN):
|
||||||
|
self.addr = address
|
||||||
|
self.connected = 1
|
||||||
|
self.handle_connect()
|
||||||
|
else:
|
||||||
|
raise socket.error, err
|
||||||
|
|
||||||
|
def accept(self):
|
||||||
|
# XXX can return either an address pair or None
|
||||||
|
try:
|
||||||
|
conn, addr = self.socket.accept()
|
||||||
|
return conn, addr
|
||||||
|
except socket.error, why:
|
||||||
|
if why[0] == EWOULDBLOCK:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
raise socket.error, why
|
||||||
|
|
||||||
|
def send(self, data):
|
||||||
|
try:
|
||||||
|
result = self.socket.send(data)
|
||||||
|
return result
|
||||||
|
except socket.error, why:
|
||||||
|
if why[0] == EWOULDBLOCK:
|
||||||
|
return 0
|
||||||
|
else:
|
||||||
|
raise socket.error, why
|
||||||
|
return 0
|
||||||
|
|
||||||
|
def recv(self, buffer_size):
|
||||||
|
try:
|
||||||
|
data = self.socket.recv(buffer_size)
|
||||||
|
if not data:
|
||||||
|
# a closed connection is indicated by signaling
|
||||||
|
# a read condition, and having recv() return 0.
|
||||||
|
self.handle_close()
|
||||||
|
return ''
|
||||||
|
else:
|
||||||
|
return data
|
||||||
|
except socket.error, why:
|
||||||
|
# winsock sometimes throws ENOTCONN
|
||||||
|
if why[0] in [ECONNRESET, ENOTCONN, ESHUTDOWN]:
|
||||||
|
self.handle_close()
|
||||||
|
return ''
|
||||||
|
else:
|
||||||
|
raise socket.error, why
|
||||||
|
|
||||||
|
def close(self):
|
||||||
|
self.del_channel()
|
||||||
|
self.socket.close()
|
||||||
|
|
||||||
|
# cheap inheritance, used to pass all other attribute
|
||||||
|
# references to the underlying socket object.
|
||||||
|
def __getattr__(self, attr):
|
||||||
|
return getattr(self.socket, attr)
|
||||||
|
|
||||||
|
# log and log_info may be overridden to provide more sophisticated
|
||||||
|
# logging and warning methods. In general, log is for 'hit' logging
|
||||||
|
# and 'log_info' is for informational, warning and error logging.
|
||||||
|
|
||||||
|
def log(self, message):
|
||||||
|
sys.stderr.write('log: %s\n' % str(message))
|
||||||
|
|
||||||
|
def log_info(self, message, type='info'):
|
||||||
|
if __debug__ or type != 'info':
|
||||||
|
print '%s: %s' % (type, message)
|
||||||
|
|
||||||
|
def handle_read_event(self):
|
||||||
|
if self.accepting:
|
||||||
|
# for an accepting socket, getting a read implies
|
||||||
|
# that we are connected
|
||||||
|
if not self.connected:
|
||||||
|
self.connected = 1
|
||||||
|
self.handle_accept()
|
||||||
|
elif not self.connected:
|
||||||
|
self.handle_connect()
|
||||||
|
self.connected = 1
|
||||||
|
self.handle_read()
|
||||||
|
else:
|
||||||
|
self.handle_read()
|
||||||
|
|
||||||
|
def handle_write_event(self):
|
||||||
|
# getting a write implies that we are connected
|
||||||
|
if not self.connected:
|
||||||
|
self.handle_connect()
|
||||||
|
self.connected = 1
|
||||||
|
self.handle_write()
|
||||||
|
|
||||||
|
def handle_expt_event(self):
|
||||||
|
self.handle_expt()
|
||||||
|
|
||||||
|
def handle_error(self):
|
||||||
|
nil, t, v, tbinfo = compact_traceback()
|
||||||
|
|
||||||
|
# sometimes a user repr method will crash.
|
||||||
|
try:
|
||||||
|
self_repr = repr(self)
|
||||||
|
except:
|
||||||
|
self_repr = '<__repr__(self) failed for object at %0x>' % id(self)
|
||||||
|
|
||||||
|
self.log_info(
|
||||||
|
'uncaptured python exception, closing channel %s (%s:%s %s)' % (
|
||||||
|
self_repr,
|
||||||
|
t,
|
||||||
|
v,
|
||||||
|
tbinfo
|
||||||
|
),
|
||||||
|
'error'
|
||||||
|
)
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def handle_expt(self):
|
||||||
|
self.log_info('unhandled exception', 'warning')
|
||||||
|
|
||||||
|
def handle_read(self):
|
||||||
|
self.log_info('unhandled read event', 'warning')
|
||||||
|
|
||||||
|
def handle_write(self):
|
||||||
|
self.log_info('unhandled write event', 'warning')
|
||||||
|
|
||||||
|
def handle_connect(self):
|
||||||
|
self.log_info('unhandled connect event', 'warning')
|
||||||
|
|
||||||
|
def handle_accept(self):
|
||||||
|
self.log_info('unhandled accept event', 'warning')
|
||||||
|
|
||||||
|
def handle_close(self):
|
||||||
|
self.log_info('unhandled close event', 'warning')
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# adds simple buffered output capability, useful for simple clients.
|
||||||
|
# [for more sophisticated usage use asynchat.async_chat]
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
class dispatcher_with_send(dispatcher):
|
||||||
|
|
||||||
|
def __init__(self, sock=None):
|
||||||
|
dispatcher.__init__(self, sock)
|
||||||
|
self.out_buffer = ''
|
||||||
|
|
||||||
|
def initiate_send(self):
|
||||||
|
num_sent = 0
|
||||||
|
num_sent = dispatcher.send(self, self.out_buffer[:512])
|
||||||
|
self.out_buffer = self.out_buffer[num_sent:]
|
||||||
|
|
||||||
|
def handle_write(self):
|
||||||
|
self.initiate_send()
|
||||||
|
|
||||||
|
def writable(self):
|
||||||
|
return (not self.connected) or len(self.out_buffer)
|
||||||
|
|
||||||
|
def send(self, data):
|
||||||
|
if self.debug:
|
||||||
|
self.log_info('sending %s' % repr(data))
|
||||||
|
self.out_buffer = self.out_buffer + data
|
||||||
|
self.initiate_send()
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# used for debugging.
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
def compact_traceback():
|
||||||
|
t, v, tb = sys.exc_info()
|
||||||
|
tbinfo = []
|
||||||
|
assert tb # Must have a traceback
|
||||||
|
while tb:
|
||||||
|
tbinfo.append((
|
||||||
|
tb.tb_frame.f_code.co_filename,
|
||||||
|
tb.tb_frame.f_code.co_name,
|
||||||
|
str(tb.tb_lineno)
|
||||||
|
))
|
||||||
|
tb = tb.tb_next
|
||||||
|
|
||||||
|
# just to be safe
|
||||||
|
del tb
|
||||||
|
|
||||||
|
file, function, line = tbinfo[-1]
|
||||||
|
info = ' '.join(['[%s|%s|%s]' % x for x in tbinfo])
|
||||||
|
return (file, function, line), t, v, info
|
||||||
|
|
||||||
|
def close_all(map=None):
|
||||||
|
if map is None:
|
||||||
|
map = socket_map
|
||||||
|
for x in map.values():
|
||||||
|
x.socket.close()
|
||||||
|
map.clear()
|
||||||
179
others/babelfish.py
Normal file
179
others/babelfish.py
Normal file
@ -0,0 +1,179 @@
|
|||||||
|
# babelizer.py - API for simple access to babelfish.altavista.com.
|
||||||
|
# Requires python 2.0 or better.
|
||||||
|
#
|
||||||
|
# See it in use at http://babel.MrFeinberg.com/
|
||||||
|
|
||||||
|
"""API for simple access to babelfish.altavista.com.
|
||||||
|
|
||||||
|
Summary:
|
||||||
|
|
||||||
|
import babelizer
|
||||||
|
|
||||||
|
print ' '.join(babelizer.available_languages)
|
||||||
|
|
||||||
|
print babelizer.translate( 'How much is that doggie in the window?',
|
||||||
|
'English', 'French' )
|
||||||
|
|
||||||
|
def babel_callback(phrase):
|
||||||
|
print phrase
|
||||||
|
sys.stdout.flush()
|
||||||
|
|
||||||
|
babelizer.babelize( 'I love a reigning knight.',
|
||||||
|
'English', 'German',
|
||||||
|
callback = babel_callback )
|
||||||
|
|
||||||
|
available_languages
|
||||||
|
A list of languages available for use with babelfish.
|
||||||
|
|
||||||
|
translate( phrase, from_lang, to_lang )
|
||||||
|
Uses babelfish to translate phrase from from_lang to to_lang.
|
||||||
|
|
||||||
|
babelize(phrase, from_lang, through_lang, limit = 12, callback = None)
|
||||||
|
Uses babelfish to translate back and forth between from_lang and
|
||||||
|
through_lang until either no more changes occur in translation or
|
||||||
|
limit iterations have been reached, whichever comes first. Takes
|
||||||
|
an optional callback function which should receive a single
|
||||||
|
parameter, being the next translation. Without the callback
|
||||||
|
returns a list of successive translations.
|
||||||
|
|
||||||
|
It's only guaranteed to work if 'english' is one of the two languages
|
||||||
|
given to either of the translation methods.
|
||||||
|
|
||||||
|
Both translation methods throw exceptions which are all subclasses of
|
||||||
|
BabelizerError. They include
|
||||||
|
|
||||||
|
LanguageNotAvailableError
|
||||||
|
Thrown on an attempt to use an unknown language.
|
||||||
|
|
||||||
|
BabelfishChangedError
|
||||||
|
Thrown when babelfish.altavista.com changes some detail of their
|
||||||
|
layout, and babelizer can no longer parse the results or submit
|
||||||
|
the correct form (a not infrequent occurance).
|
||||||
|
|
||||||
|
BabelizerIOError
|
||||||
|
Thrown for various networking and IO errors.
|
||||||
|
|
||||||
|
Version: $Id$
|
||||||
|
Author: Jonathan Feinberg <jdf@pobox.com>
|
||||||
|
"""
|
||||||
|
import re, string, urllib
|
||||||
|
|
||||||
|
"""
|
||||||
|
Various patterns I have encountered in looking for the babelfish result.
|
||||||
|
We try each of them in turn, based on the relative number of times I've
|
||||||
|
seen each of these patterns. $1.00 to anyone who can provide a heuristic
|
||||||
|
for knowing which one to use. This includes AltaVista employees.
|
||||||
|
"""
|
||||||
|
__where = [ re.compile(r'lang=..>([^<]*)</div'),
|
||||||
|
re.compile(r'name=\"q\" value=\"([^\"]*)\">'),
|
||||||
|
re.compile(r'div style=padding:10px;>([^<]+)</div'),
|
||||||
|
]
|
||||||
|
|
||||||
|
__languages = { 'english' : 'en',
|
||||||
|
'chinese_simple' : 'zh',
|
||||||
|
'chinese_traditional' : 'zt',
|
||||||
|
'french' : 'fr',
|
||||||
|
'german' : 'de',
|
||||||
|
'italian' : 'it',
|
||||||
|
'japanese' : 'ja',
|
||||||
|
'korean' : 'ko',
|
||||||
|
'spanish' : 'es',
|
||||||
|
'portuguese' : 'pt',
|
||||||
|
'russian' : 'ru',
|
||||||
|
'greek' : 'el',
|
||||||
|
'dutch' : 'nl',
|
||||||
|
}
|
||||||
|
|
||||||
|
"""
|
||||||
|
All of the available language names.
|
||||||
|
"""
|
||||||
|
available_languages = [ x.title() for x in __languages.keys() ]
|
||||||
|
|
||||||
|
"""
|
||||||
|
Calling translate() or babelize() can raise a BabelizerError
|
||||||
|
"""
|
||||||
|
class BabelizerError(Exception):
|
||||||
|
pass
|
||||||
|
|
||||||
|
class LanguageNotAvailableError(BabelizerError):
|
||||||
|
pass
|
||||||
|
class BabelfishChangedError(BabelizerError):
|
||||||
|
pass
|
||||||
|
class BabelizerIOError(BabelizerError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def clean(text):
|
||||||
|
return ' '.join(string.replace(text.strip(), "\n", ' ').split())
|
||||||
|
|
||||||
|
def translate(phrase, from_lang, to_lang):
|
||||||
|
phrase = clean(phrase)
|
||||||
|
try:
|
||||||
|
from_code = __languages[from_lang.lower()]
|
||||||
|
to_code = __languages[to_lang.lower()]
|
||||||
|
except KeyError, lang:
|
||||||
|
raise LanguageNotAvailableError(lang)
|
||||||
|
|
||||||
|
params = urllib.urlencode( { 'BabelFishFrontPage' : 'yes',
|
||||||
|
'doit' : 'done',
|
||||||
|
'tt' : 'urltext',
|
||||||
|
'intl' : '1',
|
||||||
|
'urltext' : phrase,
|
||||||
|
'lp' : from_code + '_' + to_code } )
|
||||||
|
try:
|
||||||
|
response = urllib.urlopen('http://babelfish.altavista.com/babelfish/tr', params)
|
||||||
|
except IOError, what:
|
||||||
|
raise BabelizerIOError("Couldn't talk to server: %s" % what)
|
||||||
|
except:
|
||||||
|
print "Unexpected error:", sys.exc_info()[0]
|
||||||
|
|
||||||
|
html = response.read()
|
||||||
|
try:
|
||||||
|
begin = html.index('<!-- Target text (content) -->')
|
||||||
|
end = html.index('<!-- end: Target text (content) -->')
|
||||||
|
html = html[begin:end]
|
||||||
|
except ValueError:
|
||||||
|
pass
|
||||||
|
for regex in __where:
|
||||||
|
match = regex.search(html)
|
||||||
|
if match:
|
||||||
|
break
|
||||||
|
if not match:
|
||||||
|
raise BabelfishChangedError("Can't recognize translated string.")
|
||||||
|
return clean(match.group(1))
|
||||||
|
|
||||||
|
def babelize(phrase, from_language, through_language, limit = 12, callback = None):
|
||||||
|
phrase = clean(phrase)
|
||||||
|
seen = { phrase: 1 }
|
||||||
|
results = []
|
||||||
|
if callback:
|
||||||
|
def_callback = callback
|
||||||
|
else:
|
||||||
|
def_callback = results.append
|
||||||
|
def_callback(phrase)
|
||||||
|
flip = { from_language: through_language, through_language: from_language }
|
||||||
|
next = from_language
|
||||||
|
for i in range(limit):
|
||||||
|
phrase = translate(phrase, next, flip[next])
|
||||||
|
if seen.has_key(phrase):
|
||||||
|
break
|
||||||
|
seen[phrase] = 1
|
||||||
|
def_callback(phrase)
|
||||||
|
next = flip[next]
|
||||||
|
# next is set to the language of the last entry. this should be the same
|
||||||
|
# as the language we are translating to
|
||||||
|
if next != through_language:
|
||||||
|
phrase = translate(phrase, next, flip[next])
|
||||||
|
def_callback(phrase)
|
||||||
|
if not callback:
|
||||||
|
return results
|
||||||
|
|
||||||
|
if __name__ == '__main__':
|
||||||
|
import sys
|
||||||
|
def printer(x):
|
||||||
|
print x
|
||||||
|
sys.stdout.flush();
|
||||||
|
|
||||||
|
|
||||||
|
babelize("I won't take that sort of treatment from you, or from your doggie!",
|
||||||
|
'english', 'french', callback = printer)
|
||||||
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user