def create_machine(self, name=None, package=None, dataset=None,
            metadata=None, tags=None, boot_script=None, credentials=False,
            image=None, networks=None):
        """
        ::
        
            POST /:login/machines
        
        Provision a machine in the current 
        :py:class:`smartdc.datacenter.DataCenter`, returning an instantiated 
        :py:class:`smartdc.machine.Machine` object. All of the parameter 
        values are optional, as they are assigned default values by the 
        datacenter's API itself.
        
        :param name: a human-readable label for the machine
        :type name: :py:class:`basestring`
        
        :param package: cluster of resource values identified by name
        :type package: :py:class:`basestring` or :py:class:`dict`
        
        :param image: an identifier for the base operating system image
            (formerly a ``dataset``)
        :type image: :py:class:`basestring` or :py:class:`dict`
        
        :param dataset: base operating system image identified by a globally 
            unique ID or URN (deprecated)
        :type dataset: :py:class:`basestring` or :py:class:`dict`
        
        :param metadata: keys & values with arbitrary supplementary 
            details for the machine, accessible from the machine itself
        :type metadata: :py:class:`dict`
        
        :param tags: keys & values with arbitrary supplementary 
            identifying information for filtering when querying for machines
        :type tags: :py:class:`dict`

        :param networks: list of networks where this machine will belong to
        :type networks: :py:class:`list`
        
        :param boot_script: path to a file to upload for execution on boot
        :type boot_script: :py:class:`basestring` as file path
        
        :rtype: :py:class:`smartdc.machine.Machine`
        
        If `package`, `image`, or `dataset` are passed a :py:class:`dict` containing a 
        `name` key (in the case of `package`) or an `id` key (in the case of
        `image` or `dataset`), it passes the corresponding value. The server API 
        appears to resolve incomplete or ambiguous dataset URNs with the 
        highest version number.
        """
        params = {}
        if name:
            assert re.match(r'[a-zA-Z0-9]([a-zA-Z0-9\-\.]*[a-zA-Z0-9])?$',
                name), "Illegal name"
            params['name'] = name
        if package:
            if isinstance(package, dict):
                package = package['name']
            params['package'] = package
        if image:
            if isinstance(image, dict):
                image = image['id']
            params['image'] = image
        if dataset and not image:
            if isinstance(dataset, dict):
                dataset = dataset.get('id', dataset['urn'])
            params['dataset'] = dataset
        if metadata:
            for k, v in metadata.items():
                params['metadata.' + str(k)] = v
        if tags:
            for k, v in tags.items():
                params['tag.' + str(k)] = v
        if boot_script:
            with open(boot_script) as f:
                params['metadata.user-script'] = f.read()
        if networks:
            if isinstance(networks, list):
                params['networks'] = networks
            elif isinstance(networks, basestring):
                params['networks'] = [networks]
        j, r = self.request('POST', 'machines', data=params)
        if r.status_code >= 400:
            print(j, file=sys.stderr)
            r.raise_for_status()
        return Machine(datacenter=self, data=j)