replace get_contents() with read() and add write() as public API

[bdbaddog]

This issue was originally created at: 2003-11-18 10:36:13. This issue was reported by: stephenlehighng.

stephenlehighng said at 2003-11-18 10:36:13

The man page cites node.get_contents(), but this function doesn't appear to be documented anywhere else on the man page. Other useful node functions should also be documented.

def kfile_scan(node, env, path, arg):
contents = node.get_contents()
includes = include_re.findall(contents)
return includes

issues@scons said at 2003-11-18 10:36:13

Converted from SourceForge tracker item 844606

stevenknight said at 2008-04-02 14:50:57

Try to fix documentation issues for 1.0.

gregnoel said at 2008-04-14 10:38:24

Instead of exposing get_contents(), expose a function called read() so it looks like a Python file handle. Modify examples in man page to use read().

Note that Value() nodes already have a read(), which may be incompatible.

gregnoel said at 2008-12-26 13:20:17

Adjust triage of issues.

gregnoel said at 2009-11-25 07:47:45

Change title to reflect the intended scope more accurately. Instead of using get_contents() as the way to get the contents (whether it be text or binary), create two new functions: read() which returns a normalized Unicode string and read_binary() which returns the binary contents as bytes. Review all uses of get_contents()(and get_text_contents(), but those should be easy) and replace them with either read() or read_binary() as appropriate.

Add write() and write_binary() functions as the inverse of the corresponding read() functions. (Question: should there be a way to append to a node's contents as well?) A write should mark a node as changed ("built") so that signature calculation is consistent.

Value nodes will still need a way of using a Python value. One possibility is adding a (public) read_value() and write_value() to all nodes which provides a semi-compatible interface even if the underlying object has to instantiate the value as a string (e.g., for storage in a filesystem).

Alias nodes will need semantics; maybe treating them like Dir nodes is the approach to take.

See the discussion thread[1] for more information.

[1] http://scons.tigris.org/ds/viewMessage.do?dsForumId=1272&dsMessageId=2424193

[mwichmann]

So I see that this is now marked as a documentation bug. The manpage and user guide both do mention get_contents and get_text_contents. Should they be documented? I'm assuming there's nobody stepping up to change the workings to these new read/write functions?

[bdbaddog]

Hmm. do they show up in the API docs?

[mwichmann]

sure, everything shows up in the API docs. Of course those don't distinguish between internal and public API, and we gave up worrying about it so the API docs now come with a disclaimer:

This is the internal API Documentation for SCons. The Documentation is generated using the Sphinx tool. The target audience is developers working on SCons itself, so it does not clearly delineate what is “Public API” - interfaces for use in your SCons configuration scripts which have a consistency guarantee, and what is internal, so always keep the SCons manual page around for helping with such determinations.