Skip to content

Commit 37cd4bc

Browse files
alasdairhodgealasdairhodge
committed
Merge pull request #1 from cloudsoft/docs/readme
Updates README.md
2 parents 36e9859 + be1727e commit 37cd4bc

File tree

1 file changed

+42
-143
lines changed

1 file changed

+42
-143
lines changed

‎README.md‎

Lines changed: 42 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,159 +1,58 @@
1-
# xmltodict
1+
# winrm4
22

3-
`xmltodict` is a Python module that makes working with XML feel like you are working with [JSON](http://docs.python.org/library/json.html), as in this ["spec"](http://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html):
3+
`winrm4j` is a project which enables Java applications to execute batch or PowerShell commands on a remote Windows server
4+
using [WinRM](https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx)
45

5-
[![Build Status](https://secure.travis-ci.org/martinblech/xmltodict.png)](http://travis-ci.org/martinblech/xmltodict)
6+
The code is based on the Python project [pywinrm](https://github.com/diyan/pywinrm) and uses [jython](http://www.jython.org/)
7+
to make the Python classes accessible to Java.
68

7-
```python
8-
>>> doc = xmltodict.parse("""
9-
... <mydocument has="an attribute">
10-
... <and>
11-
... <many>elements</many>
12-
... <many>more elements</many>
13-
... </and>
14-
... <plus a="complex">
15-
... element as well
16-
... </plus>
17-
... </mydocument>
18-
... """)
19-
>>>
20-
>>> doc['mydocument']['@has']
21-
u'an attribute'
22-
>>> doc['mydocument']['and']['many']
23-
[u'elements', u'more elements']
24-
>>> doc['mydocument']['plus']['@a']
25-
u'complex'
26-
>>> doc['mydocument']['plus']['#text']
27-
u'element as well'
28-
```
29-
30-
## Namespace support
31-
32-
By default, `xmltodict` does no XML namespace processing (it just treats namespace declarations as regular node attributes), but passing `process_namespaces=True` will make it expand namespaces for you:
33-
34-
```python
35-
>>> xml = """
36-
... <root xmlns="http://defaultns.com/"
37-
... xmlns:a="http://a.com/"
38-
... xmlns:b="http://b.com/">
39-
... <x>1</x>
40-
... <a:y>2</a:y>
41-
... <b:z>3</b:z>
42-
... </root>
43-
... """
44-
>>> xmltodict.parse(xml, process_namespaces=True) == {
45-
... 'http://defaultns.com/:root': {
46-
... 'http://defaultns.com/:x': '1',
47-
... 'http://a.com/:y': '2',
48-
... 'http://b.com/:z': '3',
49-
... }
50-
... }
51-
True
52-
```
53-
54-
It also lets you collapse certain namespaces to shorthand prefixes, or skip them altogether:
9+
You can download the latest binaries [here](http://mvnrepository.com/artifact/io.cloudsoft.windows/winrm4j), which also gives the details
10+
for adding winrm4j as a dependency to your project.
5511

56-
```python
57-
>>> namespaces = {
58-
... 'http://defaultns.com/': None, # skip this namespace
59-
... 'http://a.com/': 'ns_a', # collapse "http://a.com/" -> "ns_a"
60-
... }
61-
>>> xmltodict.parse(xml, process_namespaces=True, namespaces=namespaces) == {
62-
... 'root': {
63-
... 'x': '1',
64-
... 'ns_a:y': '2',
65-
... 'http://b.com/:z': '3',
66-
... },
67-
... }
68-
True
69-
```
12+
If you wish to build the binaries yourself, you can clone this project, and build it using [Maven](https://maven.apache.org/):
7013

71-
## Streaming mode
14+
`mvn clean install`
7215

73-
`xmltodict` is very fast ([Expat](http://docs.python.org/library/pyexpat.html)-based) and has a streaming mode with a small memory footprint, suitable for big XML dumps like [Discogs](http://discogs.com/data/) or [Wikipedia](http://dumps.wikimedia.org/):
16+
Before connecting to a Windows server, you will need to ensure that the server is accessible and has been configured to allow
17+
unencrypted WinRM connections over http. The following batch script will configure WinRM and open port 5985 (the default WinRM
18+
port) on the local firewall.
7419

75-
```python
76-
>>> def handle_artist(_, artist):
77-
... print artist['name']
78-
... return True
79-
>>>
80-
>>> xmltodict.parse(GzipFile('discogs_artists.xml.gz'),
81-
... item_depth=2, item_callback=handle_artist)
82-
A Perfect Circle
83-
Fantômas
84-
King Crimson
85-
Chris Potter
86-
...
20+
``` bat
21+
winrm quickconfig -q
22+
winrm set winrm/config/service/auth @{Basic="true"}
23+
winrm set winrm/config/service/auth @{CredSSP="true"}
24+
winrm set winrm/config/client/auth @{CredSSP="true"}
25+
winrm set winrm/config/client @{AllowUnencrypted="true"}
26+
winrm set winrm/config/service @{AllowUnencrypted="true"}
27+
winrm set winrm/config/winrs @{MaxConcurrentUsers="100"}
28+
winrm set winrm/config/winrs @{MaxMemoryPerShellMB="0"}
29+
winrm set winrm/config/winrs @{MaxProcessesPerShell="0"}
30+
winrm set winrm/config/winrs @{MaxShellsPerUser="0"}
31+
netsh advfirewall firewall add rule name=RDP dir=in protocol=tcp localport=3389 action=allow profile=any
32+
netsh advfirewall firewall add rule name=WinRM dir=in protocol=tcp localport=5985 action=allow profile=any
8733
```
8834

89-
It can also be used from the command line to pipe objects to a script like this:
90-
91-
```python
92-
import sys, marshal
93-
while True:
94-
_, article = marshal.load(sys.stdin)
95-
print article['title']
96-
```
35+
To test connectivity, you can install [Python](https://www.python.org/) and [pywinrm](https://pypi.python.org/pypi/pywinrm) on you development machine,
36+
then use pywinrm directly in a Python console:
9737

98-
```sh
99-
$ cat enwiki-pages-articles.xml.bz2 | bunzip2 | xmltodict.py 2 | myscript.py
100-
AccessibleComputing
101-
Anarchism
102-
AfghanistanHistory
103-
AfghanistanGeography
104-
AfghanistanPeople
105-
AfghanistanCommunications
106-
Autism
107-
...
38+
``` python
39+
import winrm
40+
s = winrm.Session('my.windows.server.com', auth=('Administrator', 'mypassword'))
41+
r = s.run_ps("ls")
42+
r.std_out
43+
r.std_err
44+
r.status_code
10845
```
10946

110-
Or just cache the dicts so you don't have to parse that big XML file again. You do this only once:
47+
To use winrm4j in Java code, you first create a `Session` object via the `WinRMFactory` class. The session object exposes the methods
48+
`run_cmd` and `run_ps`, which can be used to execute batch or PowerShell statements respectively.
11149

112-
```sh
113-
$ cat enwiki-pages-articles.xml.bz2 | bunzip2 | xmltodict.py 2 | gzip > enwiki.dicts.gz
114-
```
50+
``` java
51+
Session session = WinRMFactory.INSTANCE.createSession("my.windows.server.com", "Administrator", "mypassword");
11552

116-
And you reuse the dicts with every script that needs them:
53+
Response response = session.run_cmd("dir C:\\");
54+
System.out.println(response.getStdOut());
11755

118-
```sh
119-
$ cat enwiki.dicts.gz | gunzip | script1.py
120-
$ cat enwiki.dicts.gz | gunzip | script2.py
121-
...
56+
response = session.run_ps("ls C:\\");
57+
System.out.println(response.getStdOut());
12258
```
123-
124-
## Roundtripping
125-
126-
You can also convert in the other direction, using the `unparse()` method:
127-
128-
```python
129-
>>> mydict = {
130-
... 'response': {
131-
... 'status': 'good',
132-
... 'last_updated': '2014-02-16T23:10:12Z',
133-
... }
134-
... }
135-
>>> print unparse(mydict, pretty=True)
136-
<?xml version="1.0" encoding="utf-8"?>
137-
<response>
138-
<status>good</status>
139-
<last_updated>2014-02-16T23:10:12Z</last_updated>
140-
</response>
141-
```
142-
143-
## Ok, how do I get it?
144-
145-
You just need to
146-
147-
```sh
148-
$ pip install xmltodict
149-
```
150-
151-
There is an [official Fedora package for xmltodict](https://admin.fedoraproject.org/pkgdb/acls/name/python-xmltodict). If you are on Fedora or RHEL, you can do:
152-
153-
```sh
154-
$ sudo yum install python-xmltodict
155-
```
156-
157-
## Donate
158-
159-
If you love `xmltodict`, consider supporting the author [on Gittip](https://www.gittip.com/martinblech/).

0 commit comments

Comments
 (0)